# Social Listening Analytics API - Mentions, Sentiment, Synthesio (`nabeelbaghoor/social-listening-analytics-api`) Actor

Export social listening data from your own Synthesio account: mentions with sentiment, Synthesio rank, author, site, country and topics, filtered by query, dates, language, media and topic, plus analytics by any field, topic trees and projects. Read only. Bring your own token or API credentials.

- **URL**: https://apify.com/nabeelbaghoor/social-listening-analytics-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 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

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

# Actor input Schema

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

Projects lists every project (dashboard) the user behind your credentials can open and needs nothing else, so it is the default. Mentions pages through one project's mentions with the filters below. Analytics counts mentions by a field (over time, by sentiment, language, country, site, topic, author demographics and more) or sums a metric such as influence. Topic tree reads the topics set up in one project. Account shows the user and token scope, which is a quick credentials check.

## `reportId` (type: `string`):

The numeric Synthesio project (dashboard, called report in the API) ID, as the projects mode lists it, such as 38298. Needed by mentions, analytics and topic tree. In the projects mode, a comma separated list keeps only those projects.

## `query` (type: `string`):

Mentions and analytics. Keep only mentions matching this query, in the same syntax as the Synthesio product, such as brand AND "new york". Highlighting uses it.

## `dateFilter` (type: `string`):

Mentions and analytics. Which date the start and end filter: the mention date (period), the date it was added to the project (infused_at, best for incremental exports), the date Synthesio crawled it, or the manual review date.

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

Mentions and analytics. YYYY-MM-DD (from midnight UTC) or an ISO 8601 date-time such as 2026-09-01T00:00:00Z.

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

Mentions and analytics. YYYY-MM-DD (to the end of that day UTC) or an ISO 8601 date-time.

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

Mentions and analytics. Keep only these sentiments.

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

Mentions and analytics. ISO 639-3 codes such as eng, fra, spa, deu, or zho, zho-Hans and zho-Hant for all Chinese.

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

Mentions and analytics. ISO 3166-1 alpha-3 codes such as USA, FRA, GBR.

## `topicIds` (type: `array`):

Mentions and analytics. Keep only mentions matching any of these topics, as the topic tree mode lists them.

## `mediaGroups` (type: `array`):

Mentions and analytics. Social media, mainstream media, or both.

## `siteTypes` (type: `array`):

Mentions and analytics. Keep only these documented site categories.

## `siteIds` (type: `array`):

Mentions and analytics. Numeric Synthesio site IDs: 9938 X (Twitter), 1650630 Instagram, 21711 YouTube, 22249 Facebook, 39138 Flickr, 1109681 VK.

## `types` (type: `array`):

Mentions and analytics. Posts, comments, or both.

## `channels` (type: `array`):

Mentions and analytics. Owned or earned channels. Not available on all projects.

## `reviewStatuses` (type: `array`):

Mentions and analytics. Reviewed, unreviewed or deleted mentions.

## `twitterTypes` (type: `array`):

Mentions and analytics. Keep only retweets or quoted retweets.

## `authorIds` (type: `array`):

Mentions and analytics. Synthesio author IDs, as the author_id column of the mentions mode shows them, such as 22249-169446945261.

## `sourceIds` (type: `array`):

Mentions and analytics. Synthesio source IDs (a page, channel or account), such as 21711-4202553.

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

Mentions. Read these mentions only, by Synthesio mention ID such as 38298-55237514657.

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

Mentions and analytics. Any other documented filter as JSON, merged over the fields above: influence, synthesio_rank, ratings_normalized, classifiers, classifier_tags, communities, influencers, titles, collaboration filters, author demographics (author_genders, author_ages, author_affinities and the rest) and boolean must, should and must_not sets. Example: {"influence": {"begin": 250}}.

## `sortField` (type: `string`):

Mentions. The documented sort fields.

## `sortOrder` (type: `string`):

Mentions. Descending or ascending.

## `highlight` (type: `boolean`):

Mentions. Ask for highlighted excerpts based on the query, or on the project topics when no query is set. The excerpt goes into the snippet column.

## `analyticsField` (type: `string`):

Analytics. The field to count by. Date fields give a histogram over time; the others count mentions per value; influence, synthesio_rank and the interaction fields sum a metric.

## `analyticsType` (type: `string`):

Analytics. Leave on default to use the documented type of the field, or force terms (count per value), a date histogram, or a sum, average, min, max or stats of a numeric field.

## `analyticsBy` (type: `string`):

Analytics. A second field inside each bucket of the first, such as sentiment per day. A metric field such as influence sums inside each bucket.

## `interval` (type: `string`):

Analytics on a date field. day, week, month, year, a duration such as 2d or 12h, or milliseconds. Defaults to day.

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

Analytics on a date field. A name such as Europe/Paris (handles daylight saving) or an offset such as -02:30. Hour intervals are always UTC.

## `topN` (type: `integer`):

Analytics on a terms field. The most distinct values to return, such as the top 20 sites. Empty returns all.

## `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 does not publish a rate limit; rate limited calls are retried with a wait.

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

A Synthesio OAuth access token (they last three hours). Stored as a secret. You can instead set the DATA_API_KEY environment secret, or give the four sign-in fields below so the actor fetches a fresh token itself.

## `clientId` (type: `string`):

The client ID of your Synthesio API application, from your Synthesio sales contact. Used with the client secret, login and password when no access token is given. Falls back to the DATA_API_CLIENT_ID environment secret.

## `clientSecret` (type: `string`):

The client secret of your Synthesio API application. Falls back to the DATA_API_CLIENT_SECRET environment secret.

## `username` (type: `string`):

The login (email) of the Synthesio user the token acts for. Falls back to the DATA_API_USERNAME environment secret.

## `password` (type: `string`):

That user's Synthesio password. Sent only to the Synthesio token endpoint. Falls back to the DATA_API_PASSWORD environment secret.

## Actor input object example

```json
{
  "mode": "projects",
  "dateFilter": "period",
  "sortField": "date",
  "sortOrder": "desc",
  "highlight": false,
  "analyticsField": "date",
  "analyticsType": "default",
  "analyticsBy": "none",
  "maxResults": 100,
  "requestsPerMinute": 30
}
```

# Actor output Schema

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

One row per mention, analytics bucket, topic, project or account.

# 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-analytics-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-analytics-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-analytics-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/social-listening-analytics-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/IGeY0G6G1PPMax8dZ/builds/4K6BM8uMdrTnh2bCj/openapi.json