# Social Listening Mentions API - Sentiment, Topics, Brandwatch (`nabeelbaghoor/social-listening-mentions-api`) Actor

Export social listening data from your own Brandwatch Consumer Research account: mentions with sentiment, author, reach and location, filtered by date, source, language and country, plus mention totals, volume and sentiment charts, topics, top authors and sites. Read only. Bring your own token.

- **URL**: https://apify.com/nabeelbaghoor/social-listening-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 Mentions API - Sentiment, Topics, Brandwatch

Export the mentions, sentiment, topics and share-of-voice charts your Brandwatch Consumer Research queries collect into a dataset, a spreadsheet or a warehouse, with one row per mention or data point.

### What it collects

- **Mentions** from your saved queries and channels: date, title, snippet (or full text where the source allows it), URL, domain, page type (X, Facebook, Instagram, YouTube, news, blogs, forums, reviews and more), sentiment, author and full name, gender, account type, country, region and city, language, reach estimate, impressions, impact, monthly visitors, engagement counts per network, categories, tags, emotions and entities.
- **Filters**: date range, sentiment, page types, languages, locations (country, region, city or continent IDs), domains, author gender and account type, text search, and any other documented filter as JSON.
- **Total mentions** for a set of queries, dates and filters, in one row.
- **Chart data**: volume, authors, domains, impressions, net sentiment, reach estimate, engagement score and more, broken down by any two documented dimensions (queries, query groups, sentiment, page types, countries, languages, categories, tags, days, weeks, months and others). Weekly share of voice and daily sentiment are one run each.
- **Topics**: words, phrases, hashtags, entities, emojis, people, places or organisations with volume, share of volume, sentiment score, trending score and time series.
- **Top authors and top sites** with volume, reach estimate, sentiment breakdown and country.
- **Account lookups**: projects, queries (with their boolean search, sources and languages), query groups, and location IDs for the location filter.
- Read only, pay per result, bring your own token.

### Input

| Field | What it does |
| --- | --- |
| What to read | Projects (default, needs nothing else), queries, query groups, mentions, total mentions, chart data, topics, top authors, top sites or location lookup. |
| Project ID | Needed by every mode except projects and location lookup. The projects mode lists them. |
| Query IDs / Query group IDs | Which saved queries or groups to read. Data modes need at least one. |
| Start date / End date | The range, as YYYY-MM-DD or a timestamp with a UTC offset. Defaults to the last 30 days including today. |
| Sentiment, page types, languages | Dropdowns of the documented values. |
| Locations | Location IDs from the location lookup mode, for example a country or USA.OR for Oregon. |
| Text search, domains, author gender, account type | Further filters. |
| Extra filters | Any other documented filter, such as `{"xdomain": "example.com", "impressionsMin": 1000}`. |
| Full text | Mentions mode: full text instead of a snippet, where the source allows it. |
| Sort mentions by / Sort direction | Date, reach estimate, impressions, impact and the other documented sort fields. |
| Chart measure / first and second breakdown | Chart data mode. |
| Topic kind / metrics / order | Topics mode. |
| Query type, location type and prefix | Queries and location lookup modes. |
| Maximum results | Row cap for the run. |
| Requests per minute | Pacing. The provider allows 30 calls per 10 minutes by default. |
| Access token | Your own API access token, as a secret input. |

Run the projects mode first, then queries with a project ID, then any data mode with the query IDs.

### FAQ

#### What is a social listening mentions API used for?

Moving monitored conversation out of the dashboard and into your own tools. A brand team exports every negative mention from the last week with author and reach into a support queue. An agency pulls weekly share of voice across competitor queries into a client report. An analyst feeds mentions and topics into a warehouse to join with sales data. A comms team tracks daily sentiment and trending phrases around a launch.

#### Which data source does this actor read?

The Brandwatch Consumer Research API at api.brandwatch.com, through the routes documented at developers.brandwatch.com: projects, queries and query groups, mentions and full-text mentions, mention counts, chart data by aggregate and two dimensions, topics, top authors, top sites and locations. It reads only the queries in your own account; it does not run new searches.

#### Do I need an access token?

Yes. This actor is bring-your-own-token and never ships one. Brandwatch issues API access to Regular and Admin users on Consumer Research plans; your API user gets a token from the provider's /oauth/token endpoint, valid for a year by default. Paste it into the input, or set it once as the `DATA_API_KEY` environment secret. A missing, expired or refused token ends the run cleanly with a message saying which it was.

#### How many mentions can one run export?

Up to 100,000 rows per run. Mentions are read up to 5,000 per call and paged with the provider's cursor, which goes past the 10,000 mention limit of plain page numbers. The provider's rate limit of 30 calls per 10 minutes per client is the practical ceiling, so a large export can take a while; the actor paces itself and waits out a 429.

#### Why are some X, news or LinkedIn mentions missing text?

The provider strips the text and most metadata of X posts, limits online news to a 256 character snippet, and returns no text for LinkedIn posts, for licensing reasons. The rows still carry the ID, date, sentiment, location, reach and URL.

#### How do I filter mentions by country?

Run the location lookup mode with a prefix such as "united" and type country to get the location IDs, then put those IDs in the Locations field of any data mode. Languages, sentiment and page types are dropdowns.

#### Can this actor change anything in my account?

No. Every call is a GET. The routes that create, edit or delete queries, tags, categories, rules, lists, alerts and mentions are not used. The token travels in the Authorization header and never appears in a row or in the log.

#### How is it priced?

Pay per result: one price per mention, a lower price per analytics row (chart cell, topic, top author, top site or total) and per account record (project, query, query group or location). Requests that find nothing are free. Your Brandwatch subscription applies separately.

### Example output

```json
{
  "mode": "mentions",
  "modeLabel": "Mentions",
  "recordType": "mention",
  "projectId": "1998159493",
  "found": true,
  "id": "c54d12f5107496bac30b5ddc3478bbab",
  "name": "Jane Example",
  "queryId": 1999933037,
  "queryName": "Example Brand",
  "date": "2026-09-29T14:02:11.000+0000",
  "sentiment": "negative",
  "pageType": "forum",
  "country": "United Kingdom",
  "language": "en",
  "author": "janeexample",
  "domain": "example-forum.com",
  "url": "https://example-forum.com/t/12345",
  "title": "Delivery took three weeks",
  "snippet": "Ordered from Example Brand and the delivery took three weeks...",
  "startDate": "2026-09-01",
  "endDate": "2026-10-02",
  "reachEstimate": 540,
  "impressions": 1200,
  "impact": 31,
  "countryCode": "GBR",
  "gender": "female",
  "categoryDetails": [{ "id": "8151046", "name": "Negative", "parentId": "8151044", "parentName": "Custom Sentiment" }],
  "tags": ["Complaint"],
  "retrievedAt": "2026-10-01T09:14:52.118Z",
  "note": null
}
```

Values are illustrative; every field is one the provider documents. Chart rows carry `dimension1`, `dimension2` and `value`; topic rows carry `volume`, `percentageVolume`, `sentimentScore` and `trending`.

### Keyword map

social listening API, social media monitoring API, mentions export, brand mentions API, sentiment analysis data, share of voice, social media sentiment export, topic analysis, top authors, top sites, media monitoring data, consumer research API, Brandwatch API, Brandwatch mentions export.

# Actor input Schema

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

Projects lists every project your API user can open and needs nothing else, so it is the default. Queries and query groups list what is inside one project. Mentions, total mentions, chart data, topics, top authors and top sites read the data of saved queries or query groups and need the project ID plus at least one query or query group ID. Location lookup finds the IDs the location filter takes.

## `projectId` (type: `string`):

The numeric project ID, as the projects mode lists it. Needed by every mode except projects and location lookup.

## `queryIds` (type: `array`):

Numeric IDs of the saved queries or channels to read, as the queries mode lists them. Data modes need at least one query ID or query group ID.

## `queryGroupIds` (type: `array`):

Numeric IDs of query groups to read, as the query groups mode lists them. Can be combined with query IDs.

## `startDate` (type: `string`):

Data modes. The start of the range, as YYYY-MM-DD or a timestamp such as 2026-09-01T00:00:00-0500. Defaults to 30 days before the end date.

## `endDate` (type: `string`):

Data modes. The end of the range (exclusive), as YYYY-MM-DD or a timestamp. Defaults to tomorrow, so today is included.

## `sentiment` (type: `array`):

Data modes. Keep only mentions with these sentiments. Leave empty for all.

## `pageTypes` (type: `array`):

Data modes. Keep only mentions from these content sources. Leave empty for every source the queries collect.

## `languages` (type: `array`):

Data modes. Keep only mentions in these languages. Leave empty for all.

## `locations` (type: `array`):

Data modes. Keep only mentions posted from these locations, given as location IDs. Find a country, region, city or continent ID with the location lookup mode, for example USA.OR for Oregon.

## `search` (type: `string`):

Data modes. Keep only mentions that also match this search text.

## `domains` (type: `array`):

Data modes. Keep only mentions from these site domains, such as reddit.com.

## `genders` (type: `array`):

Data modes. Keep only mentions whose author has this gender, where the provider knows it.

## `accountTypes` (type: `array`):

Data modes. Keep only mentions from individual or organisational accounts.

## `extraFilters` (type: `object`):

Data modes. Any other documented filter as an object of filter name to value, or to a list of values for a filter that can repeat, for example {"xdomain": "example.com", "impressionsMin": 1000, "tag": \["Complaint"]}. Names outside the provider's Available Filters list are refused.

## `fullText` (type: `boolean`):

Mentions mode. Read the full text of each mention instead of a snippet, where the source allows it. X posts, online news and LinkedIn content are restricted by the provider.

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

Mentions mode. The field mentions are sorted by.

## `orderDirection` (type: `string`):

Mentions mode. Newest or largest first (desc), or the reverse (asc).

## `chartAggregate` (type: `string`):

Chart data mode. What is added up in each cell of the chart.

## `chartDimension1` (type: `string`):

Chart data mode. The first breakdown (one row group per value), such as queries, sentiment, pageTypes or countries.

## `chartDimension2` (type: `string`):

Chart data mode. The second breakdown (one row per value within each group), such as days, weeks or months for a trend.

## `timezone` (type: `string`):

Chart data and topics modes. A time zone such as America/New\_York, so days and weeks follow local time. It does not filter mentions.

## `topicsExtract` (type: `string`):

Topics mode. What to extract from the mentions.

## `topicsMetrics` (type: `array`):

Topics mode. Metrics to return with each topic. Fewer metrics answer faster. Defaults to volume, percentage volume, sentiment and trending.

## `topicsOrderBy` (type: `string`):

Topics mode. Rank topics by volume or by how fast they are trending.

## `queryType` (type: `string`):

Queries mode. List every query, or only boolean monitors or one kind of channel.

## `locationType` (type: `string`):

Location lookup mode. The kind of location to search for.

## `locationPrefix` (type: `string`):

Location lookup mode. What the location name or ID begins with, such as "united" or "usa".

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

The most rows this run returns. Mentions are read up to 5,000 per call; topics, top authors and top sites use it as their limit (top lists cap at 1,000).

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

Pacing ceiling. The provider allows 30 calls per client in any 10 minutes by default, shared with every other tool on your account, so 3 per minute is the safe default. Raise it only if your account manager raised your limit.

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

Your own Consumer Research API access token, as POST /oauth/token returns it to your API user. Stored as a secret. Can also be supplied as the DATA\_API\_KEY environment secret.

## Actor input object example

```json
{
  "mode": "projects",
  "fullText": false,
  "orderBy": "date",
  "orderDirection": "desc",
  "chartAggregate": "volume",
  "chartDimension1": "queries",
  "chartDimension2": "days",
  "topicsExtract": "phrases",
  "topicsOrderBy": "volume",
  "queryType": "all",
  "locationType": "country",
  "maxResults": 100,
  "requestsPerMinute": 3
}
```

# Actor output Schema

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

One row per mention, chart cell, topic, top author or site, total, project, query, query group or location.

# 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-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-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-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-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/ElMTzaidZJXQU24Wg/builds/uUqrI5aoEBrwhsalF/openapi.json