What changed between the Legacy API (V1) and Listen API V2, and why to migrate.
Listen API V2 replaces the Legacy API (V1). This page summarizes what changed; the pages below walk you through the migration.
BETA stageListen API V2 has moved from tech preview to BETA. The core (projects, mention search, export streams, the
Mentionmodel) is stable and safe to build on. No major breaking changes will be introduced at this stage.
What changed
| Area | Legacy API (V1) | Listen API V2 |
|---|---|---|
| Extraction model | Asynchronous endpoints: start a request, poll until the result is ready | Streams: results flow to you over one connection |
| Naming | Statements | Mentions, as in the Listen app |
| Data shape | Many flat fields | Structured objects such as author.name, author.id; see Legacy API Field Mapping |
| Rate limiting | Server time: 35 minutes of processing per 10-minute window | Number of requests only; see Rate Limiting |
| Rate-limit buckets | One shared bucket | Separate limits per endpoint group |
| Extraction endpoints | One (statements/search) | Two families: latest (mentions published in the last 7 days) and historical (the full archive) |
| Volume | Unlimited | Monthly mentions cap that depends on your plan |
Why migrate
- Simpler to use: one streaming request replaces paging and polling.
- Faster extraction: mentions arrive as a continuous stream.
- Limits that are easy to understand: requests are counted, not server time.
- Self-service: you create and manage API keys yourself in the Listen app.
Migration steps
- Migrating from Legacy API to Listen API V2: move a
statements/searchextraction loop to the latest mentions export stream, step by step. - Legacy API Field Mapping: how the V2 fields are designed, and how each legacy field maps to them.