# Social Listening API - Brand Mentions, Sentiment, YouScan (`nabeelbaghoor/social-listening-brand-mentions-api`) Actor

Export social listening data from your own YouScan account: mentions with sentiment, engagement, author, country and image labels, plus sentiment, word cloud, country, city, source, gender, age, link and histogram statistics, topics, tags and categories. Read only. Bring your own API key.

- **URL**: https://apify.com/nabeelbaghoor/social-listening-brand-mentions-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Social media, Marketing, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 mention returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

```json
{
  "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.

# Actor input Schema

## `mode` (type: `string`):

Topics lists every topic in your account with its text and Visual Insights queries and needs nothing else, so it is the default. Mentions reads the mentions a topic collected, with filters. Mentions by ID reads the mentions you name. Statistics reads one aggregated statistic of a topic. Topic tags and history collection read one topic. Spaces lists your spaces; space categories reads the categories of one space.

## `topicId` (type: `string`):

The YouScan topic ID, a number as the topics mode lists it (for example 41541). Needed by mentions, mentions by ID, statistics, topic tags and history collection.

## `spaceId` (type: `string`):

Space categories. The space ID, a number as the spaces mode lists it.

## `mentionIds` (type: `array`):

Mentions by ID. The numeric mention IDs, as the mentions mode returns them in id. Sent 500 per call.

## `statisticType` (type: `string`):

Statistics. Which aggregated statistic to read for the topic and period.

## `dateFrom` (type: `string`):

Mentions and statistics. Publication date from, as YYYY-MM-DD. Mentions also take a time with an offset, such as 2026-06-01T00:00Z. Without an offset the provider uses the key owner's time zone. Defaults to 6 days before today.

## `dateTo` (type: `string`):

Mentions and statistics. Publication date to, inclusive: 2026-06-21 includes the whole of June 21. Defaults to today.

## `timeZone` (type: `string`):

Mentions and mentions by ID. An IANA zone such as Europe/Kyiv used for dates without an offset. Defaults to the key owner's time zone.

## `addedFrom` (type: `string`):

Mentions. Only mentions YouScan saved to the topic on or after this time, as YYYY-MM-DDThh:mm:ss. Catches mentions collected late.

## `addedTo` (type: `string`):

Mentions. Only mentions saved to the topic before this time, as YYYY-MM-DDThh:mm:ss.

## `sentiments` (type: `array`):

Mentions. Keep only these sentiments.

## `excludeSentiments` (type: `array`):

Mentions. Leave out these sentiments.

## `sourceTypes` (type: `array`):

Mentions and statistics. Keep only these source types.

## `excludeSourceTypes` (type: `array`):

Mentions and statistics. Leave out these source types.

## `sources` (type: `array`):

Mentions and statistics. Keep only these sources, as domains such as instagram.com or telegram.me.

## `excludeSources` (type: `array`):

Mentions and statistics. Leave out these source domains.

## `postTypes` (type: `array`):

Mentions. Keep only these post types.

## `excludePostTypes` (type: `array`):

Mentions. Leave out these post types.

## `tagNames` (type: `array`):

Mentions. Keep only mentions with these tag names. A name the topic does not have is refused by the provider; the topic tags mode lists them.

## `excludeTagNames` (type: `array`):

Mentions. Leave out mentions with these tag names.

## `autoCategories` (type: `array`):

Mentions. Keep only these automatic categories: word of mouth, commercial, news or recipe.

## `excludeAutoCategories` (type: `array`):

Mentions. Leave out these automatic categories.

## `textQuery` (type: `string`):

Mentions. Narrow further with a query in YouScan query syntax, such as "free delivery" AND (late OR delay).

## `engagementFrom` (type: `integer`):

Mentions. Only mentions with at least this engagement count.

## `engagementTo` (type: `integer`):

Mentions. Only mentions with at most this engagement count.

## `starred` (type: `string`):

Mentions. Any, only starred, or only not starred.

## `tagged` (type: `string`):

Mentions. Any, only mentions with a tag, or only mentions without one.

## `processed` (type: `string`):

Mentions. Any, only processed, or only unprocessed mentions.

## `deleted` (type: `boolean`):

Mentions. Read the mentions moved to the Bin.

## `spam` (type: `boolean`):

Mentions. Read the mentions marked as spam.

## `dedup` (type: `boolean`):

Mentions. Return one mention per group of near-duplicate texts.

## `htmlSanitize` (type: `boolean`):

Mentions. Keep the provider default of HTML-escaped text; untick for raw text.

## `orderBy` (type: `string`):

Mentions. Newest first, oldest first, saved order or engagement. Saved order (seqAsc) pages with the provider cursor, has no depth limit and can resume; the others page with skip, which stops at 10,000 mentions.

## `sinceSeq` (type: `integer`):

Mentions with the saved order. Read only mentions saved after this sequence number; a previous run logs the value to continue from.

## `countries` (type: `array`):

Statistics. Keep only these two letter country codes, such as us or ua.

## `excludeCountries` (type: `array`):

Statistics. Leave out these two letter country codes.

## `tagIds` (type: `array`):

Statistics. Keep only mentions with these tag IDs, as the topic tags mode lists them.

## `excludeTagIds` (type: `array`):

Statistics. Leave out mentions with these tag IDs.

## `subcategoryIds` (type: `array`):

Statistics. Keep only mentions assigned these subcategory IDs, as the space categories mode lists them.

## `excludeSubcategoryIds` (type: `array`):

Statistics. Leave out mentions assigned these subcategory IDs.

## `statSize` (type: `integer`):

Statistics. How many buckets to return: up to 200 tags or words, 100 countries, regions, sources or links, 1,000 cities. Empty uses the provider default.

## `sourcesSize` (type: `integer`):

Statistics, countries (up to 20) and regions by source (up to 100). How many top sources each bucket lists.

## `histogramInterval` (type: `string`):

Statistics, histogram. The interval of each row. With day, the period must be under 3 months.

## `histogramSentiment` (type: `boolean`):

Statistics, histogram. Add positive, neutral and negative counts to each interval.

## `linksSort` (type: `string`):

Statistics, links. Rank links and hosts by mention count, total engagement or average engagement.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for. Mentions page up to 1,000 at a time.

## `requestsPerMinute` (type: `integer`):

Pacing. The provider allows 10 requests per 10 seconds and answers 429 beyond that.

## `apiKey` (type: `string`):

Your own YouScan API key, sent in the X-API-KEY header. Stored as a secret. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "topics",
  "statisticType": "sentiments",
  "starred": "any",
  "tagged": "any",
  "processed": "any",
  "deleted": false,
  "spam": false,
  "dedup": false,
  "htmlSanitize": true,
  "orderBy": "published",
  "histogramInterval": "day",
  "histogramSentiment": true,
  "linksSort": "count",
  "maxResults": 100,
  "requestsPerMinute": 30
}
```

# Actor output Schema

## `records` (type: `string`):

One row per mention, statistics bucket, topic, tag, space, category or history job.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/social-listening-brand-mentions-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/social-listening-brand-mentions-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nabeelbaghoor/social-listening-brand-mentions-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/social-listening-brand-mentions-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/VY0KitFAAjoXO0UoZ/builds/BTcRzQycdTe0TodwQ/openapi.json