YouScan Mentions API

Retrieve and update mentions collected in a topic.### How to effectively retrieve large sets of mentionsCommon scenarios are:* Load all the mentions from a given topic for a given period* Periodically poll a topic to get new mentions (see the next section)Every list response contains:- `total` — the number of mentions matching your filters, across all pages;- `mentions` — one page of results, at most `size` of them (default 10, max 1000);- `lastSeq` — a sequence-number high-water mark (see the cursor loop below).If `total` exceeds the number of mentions you received, there is more to fetch. Usethe `sinceSeq` cursor: every mention has a `seq` number, assigned in the ordermentions were saved to the topic, and cursor paging over it has no depth limit andnever skips or duplicates mentions.The cursor loop:1. Start the session: ``` GET https://api.youscan.io/api/external/topics/{topicId}/mentions?from=2018-01-01&size=1000&orderBy=seqAsc ``` `orderBy=seqAsc` returns mentions in the order they were saved to the topic.2. Take the highest `seq` value from the returned `mentions` array and repeat the request with `&sinceSeq={that value}`. `sinceSeq` is exclusive — the next page starts right after it: ``` GET https://api.youscan.io/api/external/topics/{topicId}/mentions?from=2018-01-01&size=1000&sinceSeq=8541234&orderBy=seqAsc ```3. Stop when a response returns fewer than `size` mentions.### Polling for new mentionsMentions are discovered with a delay — minutes to hours after publication — andhistory collection can add much older mentions at any time. Because `from`/`to` filterby *publication* date, repeatedly fetching a fixed window such as "yesterday 22:00 —today 07:00" misses every mention that was published inside the window but collectedafter your request ran; such mentions never show up in any later window either.Poll with the cursor instead:1. Run the cursor loop above once and persist the highest `seq` you received.2. On every subsequent run, start with `sinceSeq={persisted value}&orderBy=seqAsc`, drain the pages, and persist the new high-water mark.A mention gets its `seq` when it is saved to the topic, so late-arriving mentions arealways picked up by your next poll, no matter when they were published. Two additions:- If you also need fields that change *after* a mention is saved — engagement counts, corrected sentiment, added tags — periodically re-fetch a trailing window (say, the last 72 hours), or use the `engagementCollectedFrom` / `addedFrom` filters.- If you'd rather not poll at all, configure a webhook (see the Webhook section) and receive each new mention the moment it is saved.### Dates and time zonesDate filters match mentions by their **publication date**. Two rules save a lot ofconfusion:- **Date values without an explicit UTC offset are interpreted in the API key owner's time zone** — the time zone configured in the profile of the user the key belongs to. To make requests unambiguous, always pass explicit offsets (`from=2026-06-01T00:00Z`) or set the `timeZone` parameter.- **`to` is inclusive**: the effective upper bound is `to` plus one day. `to=2026-06-21` includes the whole of June 21.The platform UI always shows periods in the signed-in user's time zone. To reproduce anumber seen in the UI, request the same period with `timeZone` set to that user's zone —or convert the period boundaries to UTC yourself.### Deleted dataThe API returns the current state of the topic at the moment of the request:- a deleted topic returns `404` (`message: "Theme not found"`) — its mentions are no longer accessible;- deleted tags disappear from mention responses — there is no "deleted" marker;- mentions moved to the Bin are excluded unless you pass `deleted=true`.Data you exported earlier is not updated retroactively. If you keep a local copy,reconcile it periodically against the current *List topics* and *List tags* responses.### Data limitations> **Mentions from Reddit, Quora and several other forums and review websites are not accessible**> via the list mentions endpoint.> **Twitter data limitations**: We are limiting the data which can be accessed for mentions collected> from Twitter. The following adjustments are applied:> - Mention's Text and Full Text properties are removed> - Mention URL is removed> - Author URL, Author Name and Author AvatarUrl are removed> - Profile ID of the author is added to Author information (the ID itself is the ID of the Twitter Profile)> - Post ID is the ID of the Tweet> - Combining Profile ID and Post ID allows you to navigate to the exact Tweet which was collected> as the corresponding mention.### Why API data may differ from the platform UIThe API and the platform read the same storage — for the same query they return thesame data. Almost every reported discrepancy turns out to be one of the causesdescribed above:1. **Time zones.** The UI uses the viewer's time zone; your request may be using a different one — see *Dates and time zones*.2. **Sources not available via API.** Reddit, Quora and several other sources are visible in the UI but never returned by the API. Exclude them in the UI search before comparing counts — see *Data limitations*.3. **Pagination.** One request returns at most 1,000 mentions. Compare the response `total` with the UI count, not the number of rows you fetched — see *How to effectively retrieve large sets of mentions*.4. **Collection delays.** A period you fetched an hour ago may contain more mentions now — see *Polling for new mentions*.5. **Twitter restrictions.** Twitter mentions come without text, URL and author details, which makes row-by-row comparison with UI exports misleading — see *Data limitations*.6. **Deleted data.** Deleted topics, tags and binned mentions disappear from responses, while copies you saved earlier keep them — see *Deleted data*.If the numbers still differ after checking all of the above, capture the exact requestURL, the time you sent it, and the raw response — and contact support with thosedetails.