Social Listening Analytics API - Mentions, Sentiment, Synthesio

Export the mentions, sentiment and analytics your Synthesio projects collect into a dataset, a spreadsheet or a warehouse, with one row per mention, analytics bucket, topic or project. Uses your own Synthesio access token or API credentials, never changes anything in your account, and charges only for rows that carry data.

What it collects

• Mentions from any project (dashboard) you can open: ID, title, content, URL, mention date, date added to the project, crawl date, language, sentiment, Synthesio rank (0 to 10), country and location, mention type (post or comment), topics, hashtags, emoji, URLs and attachments, review status, X (Twitter) retweet type and copyright flags, joined with the author (name, profile URL, followers, and demographics such as gender, age, affinities and jobs where Synthesio computes them), the source page or channel, and the site (name, URL, site type).
• Documented filters: a query in Synthesio query syntax, a date range on the mention date, the date added (infused_at, for incremental exports), the crawl date or the review date, sentiments, languages, countries, topics, media groups (social or mainstream), site types and sites, post or comment, owned or earned channel, review status, retweets, authors, sources and mention IDs, plus any other documented filter as JSON (influence, Synthesio rank, ratings, classifiers, communities, favourite influencers, author demographics and boolean must, should and must_not sets).
• Sorting by mention date, date added, crawl date, influence, review date or Synthesio rank, and highlighted excerpts of the matching text.
• Analytics: mention volume per day, week, month or custom interval in any time zone, or counts per sentiment, language, country, site, site type, source, author, topic, hashtag, URL, title, type, channel, classifier, community and author demographics, or the sum, average, min, max or stats of influence, Synthesio rank and interactions, optionally broken down by a second field (sentiment per day, top sites per country).
• Topic tree of a project: every topic and subtopic with its ID, parent, full path, depth and colour, ready to use as topic filters.
• Projects and the account behind the token (user, scope, token lifetime), never the token itself.
• Read only, pay per result, bring your own credentials.

Input

Field	What it does
What to read	Projects (default, needs nothing else), mentions, analytics, topic tree or account.
Project ID	The numeric project (dashboard) ID, needed by mentions, analytics and topic tree. In projects mode, a comma separated list keeps only those projects.
Query	Synthesio query syntax, such as brand AND "new york".
Date filter applies to, Date start, Date end	Which date to filter (mention date, added to the project, crawled, reviewed) and the range, as YYYY-MM-DD or ISO 8601.
Sentiments, languages, countries, topic IDs	Positive, neutral, negative, undefined; ISO 639-3 languages; ISO 3166-1 alpha-3 countries; topic IDs from the topic tree mode.
Media groups, site types, site IDs, mention types, channels	Social or mainstream; the 17 documented site categories; numeric sites such as 9938 for X; posts or comments; owned or earned.
Human review status, X (Twitter) types, author, source and mention IDs	The remaining list filters.
Extra filters	Any other documented filter as a JSON object, such as {"influence": {"begin": 250}}.
Sort mentions by, Sort order, Highlight matches	Mentions mode.
Analytics field, Analytics type, Break down by, Interval, Time zone, Top N values	Analytics mode.
Maximum results	Row cap for the run.
Requests per minute	Pacing.
Access token	A Synthesio OAuth access token, as a secret input, or the DATA_API_KEY secret.
Client ID, Client secret, Login, Password	Instead of a token: your Synthesio API application and a user, so the actor signs in once per run and renews the token if it expires. All secret inputs.

Run the projects mode first, then the topic tree with a project ID, then mentions or analytics with the project ID and any topic IDs.

Access and limits on the Synthesio side

• The Synthesio API comes with an enterprise Synthesio subscription. Your Synthesio sales contact issues the API application (client ID and secret); tokens are created for a Synthesio user and see exactly the projects that user can open.
• Access tokens last 10,800 seconds (three hours). With the four sign-in fields the actor fetches a token at the start of the run and once more if it expires.
• Mentions are paged with up to 1,000 per call. The provider does not publish a paging depth or rate limit; if it stops serving deeper pages the actor keeps what it read and says so. For large exports, filter on the date added to the project (infused_at) and run day by day.
• Some mentions carry copyright restrictions (extra_properties.restricted_usage): Synthesio then blanks the content of some sites, and for X posts only Synthesio's own fields such as the rank remain. Analytics still count them.

FAQ

What is a social listening API used for?

Getting the conversation a listening platform collects out of its dashboard and into your own tools. A brand team exports every negative mention from the last day with author and site into a support queue. An insights team pulls daily mention volume by sentiment and topic into a BI dashboard. An agency joins Synthesio mentions with campaign and sales data in a warehouse. A research team reads author demographics and affinities for an audience study.

Which data source does this actor read?

The Synthesio API at rest.synthesio.com, through the routes documented at developer.synthesio.com (Ipsos Synthesio): the security API (token and user), the workspace API (projects), the topic API (topic tree) and the mention API (search and analytics). The documentation and the live host were checked on 2026-10-03.

Do I need a Synthesio account?

Yes. This actor is bring-your-own-credentials and never ships any. API access is part of an enterprise Synthesio subscription; ask your Synthesio sales contact for an API application. Then either paste an access token, or give the client ID, client secret, user login and password so the actor signs in itself. Missing or refused credentials end the run cleanly with a message saying which it was.

How do I export mentions incrementally?

Use the mentions mode with the date filter set to "Added to the project (infused_at)", sort by the same field ascending, and set the date start to the infused_at of the last mention of the previous run. Synthesio documents this pattern for exports that never miss late-arriving mentions.

How do I get mention volume by sentiment per day?

Choose the analytics mode with analytics field date, interval day and break down by sentiment, with your project ID and a date range. Each row is a day (dimension1) and a sentiment (dimension2) with the count in value; one row per day also carries the day total. Net sentiment is (positive minus negative) divided by (positive plus negative).

Can this actor change anything in my Synthesio account?

No. It reads only. The mention search and analytics calls are POST requests because Synthesio designs its search actions that way, but they change nothing. The one documented write, the Coding bulk route that edits sentiment, tags and review status, is not used. Tokens, client secrets and passwords are never logged and are stripped from any error text.

How is it priced?

Pay per result: one price per mention, a lower price per analytics row, and the lowest per project, topic or account row. Requests that find nothing are free. Your Synthesio subscription applies separately.

Example output

{
  "mode": "mentions",
  "modeLabel": "Mentions",
  "recordType": "mention",
  "reportId": "38298",
  "found": true,
  "id": "38298-55237976431",
  "name": "Example Brand",
  "date": "2026-09-30T15:11:15+02:00",
  "sentiment": "neutral",
  "language": "eng",
  "country": "USA",
  "author": "Example Brand",
  "site": "Facebook",
  "title": "Example Brand named a leader in social listening",
  "snippet": "This just in: Example Brand has been named a leader...",
  "url": "https://www.facebook.com/permalink.php?story_fbid=1&id=2",
  "rank": 0.86,
  "topics": ["c0ifqvcbb64sdb6uhg3g"],
  "author_id": "22249-169446945261",
  "source_id": "22249-567",
  "site_id": "22249",
  "infused_at": "2026-09-30T16:26:32+02:00",
  "authorUrl": "https://www.facebook.com/ExampleBrand/",
  "authorFollowers": 649,
  "siteTypeId": "17",
  "dimension1": null,
  "dimension2": null,
  "value": null,
  "totalHits": null,
  "retrievedAt": "2026-10-03T09:14:52.118Z",
  "note": null
}

Values are illustrative; every field is one the provider documents. Analytics rows carry dimension1 (the time bin or value, such as 2026-09 or eng), dimension2 (the breakdown value) and value; topic rows carry path, parentId and depth.

Keyword map

social listening API, social media monitoring API, consumer intelligence API, brand mentions API, mentions export, sentiment analysis data, share of voice, mention volume analytics, author demographics, topic tree, media monitoring data, Synthesio API, Synthesio mentions export, Ipsos Synthesio data.