Mentions extraction loop

If you extract mentions with the Legacy API (V1) statements/search endpoint, this guide shows how to do the same with Listen API (V2). For a summary of what changed and the BETA status, see Migration Guide.

You used statements/search

A typical legacy integration runs an endless loop:

1. List your topics.
2. For each topic, call statements/search with indexedFrom set to the last time you checked, and page through the results.
3. Store the mentions, remember the newest indexing time, and move to the next topic.
4. After the last topic, start again from the first one.

Now use the latest mentions export stream

The new API runs the same loop on the latest (recent) mentions export stream. Instead of paging, you open one stream per project; it delivers every matching mention and then closes. The collectedAt time of the last mention you received becomes your cursor, just as indexedFrom was.

How you did it with the legacy API

# 1. List topics
curl https://sentione.com/api/topic/list \
  -H 'X-API-KEY: your-legacy-api-key'

# 2. For each topic: fetch everything indexed since the last run, page by page
curl -X POST https://sentione.com/api/statements/search \
  -H 'X-API-KEY: your-legacy-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "topicId": 404615,
    "indexedFrom": "2026-10-20 10:00:00.000 CET",
    "rows": 1000,
    "page": 1
  }'

# 3. Move to the next topic; after the last one, start again

How you do it with the new API

1. Get an API key

Create a new key in the Listen app: open Organization → API Access and click Create new key. Send it in the X-API-KEY header, as before. See Authentication.

2. List your projects

Topics are now called projects.

curl https://sentione.com/api/public/v2/projects \
  -H 'X-API-KEY: S1-APIKEY-your-key-copied-from-organization-tab'

3. Extract a project from its cursor

Filter by collectedAt from the project's saved cursor and sort by CollectedAtAscending. On the first run, leave out collectedAt to get everything published in the last 7 days.

curl -N -X POST https://sentione.com/api/public/v2/projects/404615/mentions/recent/search/stream \
  -H 'X-API-KEY: S1-APIKEY-your-key-copied-from-organization-tab' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/x-ndjson' \
  -d '{
    "filters": {
      "collectedAt": { "from": "2026-10-20T09:00:00Z" }
    },
    "sortType": "CollectedAtAscending"
  }'

Each line is one event. Store mention events and skip heartbeat events, which only keep the connection alive. The stream closes when all matching mentions have been delivered.

{"event":"mention","id":"smid-wcuEd…","data":{"id":"smid-wcuEd…","type":"Post","publishedAt":"2026-10-20T09:10:00Z","collectedAt":"2026-10-20T09:12:15Z","content":{"text":"…","sentiment":"Positive"}}}
{"event":"heartbeat","data":{"date":"2026-10-20T09:12:20Z"}}

4. Save the cursor

Store the collectedAt of the last mention as this project's cursor.

5. Move to the next project

Repeat steps 3–4 for each project.

6. Start again

After the last project, go back to the first one and extract from its saved cursor. Repeat indefinitely.

Each mention also carries deprecatedV1Fields.id, its legacy ID, so you can match it with data you already stored. For all other fields, see Legacy API Field Mapping.

New limitations

The cap is shared with mention exports made in the Listen app. When it is reached, requests fail with 429 Too Many Requests until the cap renews. Narrow your projects to the mentions you need, and contact your account manager if your volume requires a higher cap. See Mentions cap and Pricing.

Other limits

• 2 concurrent stream connections per organization. Extract projects one after another, or two at a time.
• The latest stream covers mentions published within the last 7 days. For older mentions, use the historical mentions export stream.
• Request limits per endpoint group; see Rate Limiting.

New capabilities

Beyond replacing statements/search, Listen API (V2) adds:

• Historical export: download a project's full archive with the historical mentions export stream.
• Live streams: with only a few projects, keep a live stream open per project and receive mentions as they are collected, without a cursor.
• Server-side filters: filter by sentiment, source, mention type, language and country with dedicated request fields, and search mention text with Listen Query Language.
• Discussions: fetch a whole thread, for example all comments under a post, with the discussion export stream.
• Engagement updates: follow likes, shares and comments changing on collected mentions with the engagement updates live stream.
• Single mention lookup: get a mention by ID or its parent mention.
• Tagging: add tags to mentions from your integration.
• Project management: create and update projects through the API.