List mentions with the Mention API
Lists the mentions an alert collected, with title, text, URL, source, language, tone and folder. The response has _links.more, whose href carries the cursor of the older mentions. Some filters cannot be combined, as each one says.
- Identifier
- mention_list_mentions
The request
POST https://connect.reportei.com/api/tools/mention_list_mentions/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"account_id": "<account_id>",
"alert_id": "<alert_id>"
}
}Your system sends your customer's connection id and the tool arguments. The headers are the same as the rest of the Connect API: your product's token and your customer's token.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| account_id | string | Yes | Id of the account, from Get account. |
| alert_id | string | Yes | Id of the alert, from List alerts. |
| limit | integer | No | Mentions per page, up to 1000. The default is 20; a small limit answers faster. |
| cursor | string | No | The cursor parameter of _links.more.href in the previous response, to read older mentions. |
| since_id | integer | No | Only the mentions found after the mention with this id, from List mentions, sent as a number. Not combinable with before_date, not_before_date or cursor. |
| before_date | string | No | Only the mentions published before this date-time, for example 2026-01-31T00:00:00.0+00:00. The mentions come ordered by publication date. |
| not_before_date | string | No | Ignores the mentions published before this date-time. Only together with before_date. |
| folder | string | No | Only the mentions of this folder.Values: inbox, archive, spam, trash |
| unread | integer | No | 1 returns only unread mentions. Not combinable with favorite, q or tone.Values: 0, 1 |
| favorite | integer | No | 1 returns only favorite mentions. Not combinable with folder spam or trash.Values: 0, 1 |
| tone | integer | No | Only the mentions of this tone: -1 negative, 0 neutral, 1 positive.Values: -1, 0, 1 |
| source | string | No | Only the mentions of this source code, from the alert_sources of Get app data. Only for plans with search access. |
| languages | string | No | Only the mentions in this language code, such as en, from the alert_languages of Get app data. |
| countries | string | No | Only the mentions from this country code, such as US, from the alert_countries of Get app data. |
| include_children | integer | No | 1 also returns the child mentions.Values: 0, 1 |
| sort | string | No | Sort order of the mentions. Only for plans with search access.Values: published_at, author_influence.score, direct_reach, cumulative_reach, domain_reach |
| q | string | No | Keywords, and filters that the other arguments cannot combine, for example nasa source:(facebook OR twitter) tone:(neutral OR positive) published_at:[2026-01-01 TO 2026-01-31]. Only for plans with search access. |
| timezone | string | No | Time zone of the dates in q, for example America/Sao_Paulo. |
Supported connections
Your customer connects their Mention account once, with one of the modes below. The same connection serves every tool of the toolkit.
API key
Your customer pastes the app's key on a Connect screen, or your system sends the key with POST /api/customer-toolkits, with no screen.
The response
On success, Connect preserves the app's response status and body. HTTP errors returned by the app use the {error, api_error} envelope; authentication or validation can fail before execution. The X-Toolkit-Execution-Id header identifies the recorded execution, available at GET /api/tools/executions/{uuid}.
Ready for AI agents
This tool's input is a JSON Schema, available at GET /api/tools/mention_list_mentions. It becomes your agent's tool definition with no conversion.
Other Mention tools
- Get accountGETReturns the Mention account of the connection with its id, name, email and language. The id is the account_id that the other tools take.
- Get app dataGETReturns the reference lists of Mention: alert_languages, alert_countries and alert_sources, whose keys are the codes that alerts and mention filters take, plus alert_tones and mention_folders.
- List alertsGETLists the alerts of the account with id, name, query, languages, sources and mention counts per folder. When there are more alerts, the response has _links.more with the cursor of the next page.
- Create alertPOSTCreates an alert, which starts collecting the mentions that match its query, and returns it with its id. Collected mentions count against the quota of the Mention plan.
- Update alertPUTUpdates an alert, usually to refine its query, and returns it. Only the fields sent change. A query sent replaces the current one and needs its type.
- Get mentionGETReturns one mention with title, text, URLs, source, language, tone, folder, the read and favorite flags, its tasks and the first page of its child mentions.
- Update mentionPUTCurates a mention: marks it read or favorite, moves it to a folder, sets its tone or tags it, and returns it. Only the fields sent change. The content of a mention never changes.
- List tagsGETLists the tags of an alert with id, name, mention count and auto-tagging keywords. The id is what the tags of Update mention take.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
