# YouScan Mentions API **Canonical:** https://apis.io/apis/youscan/youscan-mentions-api/ **Provider:** YouScan — https://apis.io/providers/youscan/ **Base URL:** https://api.youscan.io/api/external **Documentation:** https://developers.youscan.io/ YouScan Mentions API is one of 8 APIs that [YouScan](https://apis.io/providers/youscan/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Mentions. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference. Retrieve and update mentions collected in a topic. ### How to effectively retrieve large sets of mentions Common 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. Use the `sinceSeq` cursor: every mention has a `seq` number, assigned in the order mentions were saved to the topic, and cursor paging over it has no depth limit and never 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 mentions Mentions are discovered with a delay — minutes to hours after publication — and history collection can add much older mentions at any time. Because `from`/`to` filter by *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 collected after 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 are always 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 zones Date filters match mentions by their **publication date**. Two rules save a lot of confusion: - **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 a number 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 data The 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 UI The API and the platform read the same storage — for the same query they return the same data. Almost every reported discrepancy turns out to be one of the causes described 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 request URL, the time you sent it, and the raw response — and contact support with those details. ## Machine-readable artifacts (4) - **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/youscan/refs/heads/main/openapi/youscan-mentions-api-openapi.yml - **LLMsTxt** — https://raw.githubusercontent.com/api-evangelist/youscan/refs/heads/main/llms/youscan-llms.txt - **Documentation** — https://developers.youscan.io/ - **APIReference** — https://developers.youscan.io/api/ ## Other YouScan APIs (7) - [YouScan Data Import API](https://apis.io/apis/youscan/youscan-data-import-api/) - [YouScan History API](https://apis.io/apis/youscan/youscan-history-api/) - [YouScan Spaces API](https://apis.io/apis/youscan/youscan-spaces-api/) - [YouScan Statistics API](https://apis.io/apis/youscan/youscan-statistics-api/) - [YouScan Tags API](https://apis.io/apis/youscan/youscan-tags-api/) - [YouScan Topics API](https://apis.io/apis/youscan/youscan-topics-api/) - [YouScan Webhook API](https://apis.io/apis/youscan/youscan-webhook-api/) ## Tags Mentions --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/youscan/youscan-mentions-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/youscan/.