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

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