Social Listening API - Brand Mentions, Sentiment, YouScan

Export the brand mentions, sentiment and audience statistics your YouScan topics collect into a dataset, a spreadsheet or a warehouse, with one row per mention or statistics bucket. Uses your own YouScan API key, never changes anything in your account, and charges only for rows that carry data.

What it collects

• Mentions from any topic: text and full text, title, URL, publication and collection time, sentiment, aspect sentiment, source and source type (social networks, messengers, reviews, news, blogs, forums), post type, language, country, region and city, likes, comments, reposts, views, reactions and engagement, potential reach, author and publication place profiles (name, nickname, subscribers, gender, age, jobs, interests), tags, auto categories, subjects, categories, collection method and the Visual Insights image labels (brands and logos, objects, scenes, activities, people, colours and text on images).
• The documented mention filters: publication period with time zone, date added to the topic, sentiment, source type, source domain, post type, tag names, auto categories (word of mouth, commercial, news, recipe), a YouScan text query, engagement range, starred, tagged and processed flags, Bin and spam mentions, near-duplicate grouping, and four orders.
• Full exports without a depth limit: the saved order follows YouScan's own sequence cursor, so one run can read past 10,000 mentions and logs a resume number so the next run picks up only new mentions.
• Mentions by ID: re-read up to 500 mentions per call, for example to refresh engagement counts.
• Statistics for any period and filter set: sentiment, tags, word cloud, countries (with sentiment, top sources, authors and engagement), cities, regions and sources with sentiment, regions by source with sentiment, a histogram of mentions, authors, engagement and sentiment per hour, day, week, month, quarter or year, author genders and ages, top links and hosts, and summary engagement metrics (engagement, authors, sources, views, subscribers).
• Account setup: topics with their text and Visual Insights queries and filters, topic tags, the history collection job (status, progress, mentions saved), spaces, and categories with their subcategories.
• Read only, pay per result, bring your own API key.

Input

Field	What it does
What to read	Topics (default, needs nothing else), mentions, mentions by ID, statistics, topic tags, history collection, spaces or space categories.
Topic ID	The number the topics mode lists. Needed by every topic mode.
Space ID	Space categories mode.
Mention IDs	Mentions by ID mode.
Statistic	Statistics mode: sentiments, tags, words, countries, cities, regionsSentiments, sourcesSentiments, regionsSourcesSentiments, histogram, genders, ages, links or metrics.
Start date / End date	Publication period. to is inclusive. Mentions also take a time with an offset. Defaults to the last 7 days.
Time zone	IANA zone for mention dates without an offset.
Added to topic from / until	Mentions saved to the topic in a window, to catch late arrivals.
Sentiment, source types, sources, post types, tag names, auto categories (and their exclusions)	Mention filters. Source types and sources also filter statistics.
Text query	Narrow mentions with YouScan query syntax.
Minimum / maximum engagement, starred, tagged, processed, Bin, spam, group near duplicates, HTML-safe text	Further mention filters and options.
Order / Resume sequence number	Newest, oldest, saved order (cursor) or engagement; the resume number continues a saved order export.
Countries, tag IDs, subcategory IDs (and their exclusions)	Statistics filters.
Statistic size, sources per bucket, histogram interval, histogram sentiment, rank links by	Statistics options.
Maximum results	Row cap for the run.
Requests per minute	Pacing, 60 at most.
API key	Your own YouScan API key, as a secret input.

Run the topics mode first, then mentions or statistics with a topic ID.

Limits on the YouScan side

• API access depends on your YouScan plan; a plan without it answers HTTP 402 and the run ends with a message saying so.
• Each key belongs to one user and inherits that user's topic permissions. Reading mentions, statistics and tags needs View permission on the topic.
• Rate limit: 10 requests per 10 seconds and 5 in parallel per user, answered with HTTP 429 beyond that. This actor sends one request at a time and retries a 429 after the window.
• A mentions page holds up to 1,000 mentions. Skip paging stops below 10,000; the saved order cursor has no depth limit.
• Mentions from Reddit, Quora and several other forums and review sites are not available through the API. Twitter (X) mentions come without text, URL and author name, but keep the post ID and author profile ID.
• Date values without an offset are read in the key owner's time zone, so set the time zone input to reproduce numbers seen in the YouScan interface.

FAQ

What is a social listening API used for?

Moving the conversation YouScan monitors out of its dashboard and into your own tools. A brand team exports every negative mention of the week with engagement and author into a support queue. An agency pulls daily mention volume and sentiment for competitor topics into a client report. An analyst loads every mention of a topic into a warehouse with the saved order cursor and refreshes it daily. A marketing team tracks which logos and scenes appear in images that mention the brand.

Which data source does this actor read?

The YouScan API at api.youscan.io/api/external, through the routes documented at developers.youscan.io/api and in YouScan's published OpenAPI 3.1 file (developers.youscan.io/api/openapi.yaml, linked from developers.youscan.io/llms.txt): List topics, List spaces, List categories, List tags, History collection details, List mentions, Get mentions by IDs, and the thirteen Statistics endpoints. The documentation and the live host were checked on 2026-10-03.

Do I need a YouScan API key?

Yes. This actor is bring-your-own-key and never ships one. YouScan issues API keys per user on plans that include API access; ask your YouScan account manager or support for one. Paste it into the input, or set it once as the DATA_API_KEY environment secret. A missing or refused key, a plan without API access and a topic permission that is too low each end the run cleanly with a message saying which it was.

How do I export every mention of a topic, not just the first 10,000?

Choose the mentions mode with the order set to saved order (seqAsc). The actor follows YouScan's sequence cursor, reads 1,000 mentions per call with no depth limit, and logs the highest sequence number it read. Put that number in the resume sequence number input on the next run to read only mentions saved since, including ones published earlier but collected late.

How do I get mention volume by sentiment per day?

Choose the statistics mode, statistic histogram, interval day, with your topic ID and period. Each row is one day with value (mentions), authorsCount, engagement and positive, neutral and negative counts. With the day interval, keep the period under 3 months.

Does it include image recognition data?

Yes, when your topics collect it. Each mention row keeps YouScan's Visual Insights fields: imageBrands, imageObjects, imageScenes, imageActivities, imagePeople, imageColors and imageTexts, plus collectionMethods, which says whether the mention matched by text, text on an image, a logo or other image attributes.

Can this actor change anything in my YouScan account?

No. Every call is a GET. The routes that create topics, edit queries, delete topics, start or stop history collection, create tags, bulk update mentions and import mentions are not used. The key travels only in the X-API-KEY header, never in a URL, and is never logged.

How is it priced?

Pay per result: one price per mention, a lower price per statistics row, and the lowest per account record (topic, tag, space, category or history job). Requests that find nothing are free. Your YouScan subscription applies separately.

Example output

{
  "mode": "mentions",
  "modeLabel": "Mentions",
  "recordType": "mention",
  "topicId": "41541",
  "found": true,
  "id": "241032672",
  "name": "Jane Example",
  "date": "2026-09-30T08:13:03+00:00",
  "sentiment": "negative",
  "sourceType": "social",
  "source": "instagram.com",
  "country": "us",
  "language": "eng",
  "author": "Jane Example",
  "title": null,
  "snippet": "Third late delivery this month from Example Brand...",
  "url": "https://www.instagram.com/p/example",
  "engagement": 20,
  "reach": 1840,
  "dimension1": null,
  "dimension2": null,
  "value": null,
  "totalCount": null,
  "retrievedAt": "2026-10-03T09:14:52.118Z",
  "note": null,
  "seq": 3571010,
  "published": "2026-09-30T08:13:03+00:00",
  "addedAt": "2026-09-30T08:40:59.950Z",
  "text": "Third late delivery this month from Example Brand...",
  "postType": "post",
  "contentTypes": ["text", "image"],
  "tags": ["delivery"],
  "autoCategories": ["wom"],
  "imageBrands": ["example brand"],
  "imageObjects": ["box"],
  "region": "California",
  "city": "Los Angeles",
  "authorProfile": { "name": "Jane Example", "nickname": "janeexample", "subscribers": 1840, "gender": "female" },
  "engagementDetail": { "likes": 15, "comments": 3, "reposts": 2, "engagement": 20 }
}

Values are illustrative; every field is one the provider documents. Statistics rows carry statisticType, dimension1 (the bucket, such as a country code, word, source or interval start), dimension2 (the source in regions by source, or link or host), value (the count) and totalCount, plus positive, neutral and negative where the statistic has a sentiment split.

Keyword map

social listening API, brand mentions API, social media monitoring API, mentions export, sentiment analysis data, image recognition social listening, visual insights, logo detection mentions, word cloud API, share of voice, mention volume histogram, audience demographics, YouScan API, YouScan mentions export, YouScan statistics.