Migrating from Legacy API to Listen API V2

If you extract mentions with the legacy 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

In V2 the same loop uses 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: $LEGACY_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: $LEGACY_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 Listen API V2

1. Get a V2 API key. V2 does not accept legacy keys. Create one yourself in the Listen app: open Organization → API 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: $V2_KEY"

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: $V2_KEY" \
  -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, V2 returns 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.

What's new in V2

• 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: sentiment, source, mention type, language, country and full-text search in 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.