# Social Listening API - Mentions Export, Sentiment, SentiOne (`nabeelbaghoor/social-listening-mentions-export-api`) Actor

Export social listening mentions from your own SentiOne Listen projects: posts, comments, articles and reviews from social media, news, blogs, forums and video, with sentiment, author, followers, engagement, language and location. Recent, historical and stream export. Read only. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/social-listening-mentions-export-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 - Mentions Export, Sentiment, SentiOne

Export the public mentions your SentiOne Listen projects collect across social media, news sites, blogs, forums, video and review sites into a dataset, a spreadsheet or a warehouse, with sentiment, author, followers, engagement, language and location on every row. Uses your own Listen API key, never changes anything in your account, and charges only for rows that carry data.

### What it collects

- **Mentions** of any Listen project you can open: mention ID, publish and collection time, source type (Facebook, Instagram, X (Twitter), TikTok, Reddit, websites and news, blogs, forums, video, reviews, imported, other), mention type (post, comment, article, private message, share), title, text, URL, sentiment, language, country, region and city.
- **Authors and channels**: author name, ID, gender and follower count, and the social channel (fan page, profile, YouTube channel) the mention came from.
- **Engagement**: influence score (1 to 10), engagement rate, likes, shares, comments and views, plus Facebook reactions, X retweets and favourites where the source reports them, and the star rating of review mentions such as Google Maps reviews.
- **Threads**: the discussion ID that ties a post to its comments, the text of the parent post when the source provides it, a discussion mode that reads a whole thread, and a parent mode that returns the post a comment replies to.
- **Documented filters**: a Listen Query Language text query (AND, OR, NOT, exact phrases, wildcards), source types, mention types, sentiments, languages, and a time range on the published or collected time, with nine documented sort orders.
- **Two ways to read**: search modes page 25 mentions a call, and export stream modes deliver large volumes over one long-running connection.
- **Projects**: the ID and name of every Listen project your key reaches, ready to use in the other modes.
- Read only, pay per result, bring your own key.

### How to use it

1. In the SentiOne app, open **Organization > API Access** and generate an API key. It starts with `S1-APIKEY-`. API access is an add-on to Listen: the **Basic** tier is free, the **Enterprise** tier is sold by SentiOne.
2. Paste the key into the **API key** field (stored as a secret), or set the `DATA_API_KEY` environment secret.
3. Run the default **Projects** mode to see your project IDs.
4. Pick a mention mode, set the project ID (optional when the key reaches one project), add filters, and run.

Which modes each tier reaches, per the provider's documentation:

| Mode | API tier | Provider rate limit |
| --- | --- | --- |
| Projects | Basic | 300 calls an hour |
| Recent mentions (last 7 days) | Basic | 30 search calls an hour, shared |
| Historical mentions | Enterprise | 30 search calls an hour, shared |
| Export stream, historical or recent | Enterprise | 14,400 calls an hour, 2 open streams |
| Discussion thread, recent | Basic | 30 search calls an hour, shared |
| Discussion thread, any period | Enterprise | 30 search calls an hour, shared |
| Mentions by ID, parent post by ID | Basic | 60 calls an hour |

### Input

| Field | What it does |
| --- | --- |
| What to read | Projects (default, needs nothing else), recent or historical mentions, export stream (historical or recent), discussion thread (recent or any period), mentions by ID, or parent post by ID. |
| Project ID | Mention and export modes. Picked automatically when the key reaches one project. |
| Search query | Listen Query Language filter on the mention text, up to 500 characters. |
| Last days | Read from this many days back. Recent modes see at most 7. Ignored when a date is set. |
| Date start, Date end | Custom range as `YYYY-MM-DD` or ISO 8601. The end is exclusive; a plain date includes that day. |
| Time range applies to | Published time or collected time. |
| Source types, Mention types, Sentiments, Languages | The documented filters; leave empty for all. |
| Sort by | Published or collected time, influence score, engagement rate, likes, shares or author followers. |
| Discussion ID | Discussion modes, from the `discussionId` column of a mention row. |
| Mention IDs | Mention modes, one `smid-...` ID per line. |
| Anonymize personal data | Export streams only: hash authors, or authors, channels and location. |
| Maximum results | Row cap for the run. Streams are sent it as their documented limit. |
| API key | Your Listen API key, as a secret input, or the `DATA_API_KEY` secret. |

### Access and limits on the SentiOne side

- **Monthly mentions cap**: raw mentions read through the API count against a monthly cap set in your contract (10K on the free Basic tier, up to 100M on Enterprise). Every mention route answers HTTP 429 once it is spent; the run then ends cleanly and says so. Export streams are sent your maximum results as their documented `limit`, so a run never spends more of the cap than you asked for.
- **Hourly rate limits** are per endpoint (see the table above). A short wait is honoured; when the limit resets further away the run keeps the rows it already has and ends with a message saying when to run again. For more than a few hundred mentions, use an export stream mode.
- **Tier**: a Basic key calling an Enterprise mode is refused with "Insufficient permissions"; the run ends cleanly naming the tier it needs.
- **The API is a tech preview**: SentiOne marks the V2 Listen API as in active development and rolls features out gradually, so some accounts may see a mode before others.

### Terms of use

SentiOne's Terms of Service say that using content shared through the system in a manner other than the service intends requires SentiOne's consent, and that when quoting any information obtained from it you must name the source and the date of acquisition with the note "Source: sentione.com". Every mention row carries that note in `sourceAttribution`, next to `retrievedAt` as the acquisition date. Use the export within the terms of your own SentiOne agreement, and keep the attribution wherever you quote the data.

### FAQ

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

Getting the mentions a social listening platform collects out of its dashboard and into your own tools. A customer care team pulls every negative Facebook and X comment of the last day into a ticket queue. A brand team exports a quarter of mentions with sentiment and reach into a BI dashboard to track share of voice. An analyst feeds review mentions with star ratings into a product feedback model.

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

The SentiOne Listen API (V2) at sentione.com/api/public/v2, documented at listen.help.sentione.com/reference. It calls the project list, project, recent and historical mention search, export stream, discussion search, mention and parent mention routes. The documentation and the live host were checked on 2026-10-05. The legacy API is not used: its keys are separate and SentiOne has said V2 will replace it.

#### Do I need a SentiOne account?

Yes. This actor is bring-your-own-key and never ships one. You need SentiOne Listen with API access; the Basic API tier is free and reaches the project list, recent mentions, recent discussions and mention lookups. A missing or refused key ends the run cleanly with a message saying which it was.

#### How do I export mentions incrementally without missing late arrivals?

Use an export stream or search mode with "Time range applies to" set to collected time, sort by collected time oldest first, and set the date start to the time of your previous run. Mentions SentiOne collects late are then picked up on the next run.

#### What is the difference between search and export stream modes?

Search modes return 25 mentions per call and the provider allows 30 search calls an hour, which suits a few hundred recent mentions. Export streams deliver mentions continuously over one connection until the range is exhausted or your maximum is reached, which suits bulk exports of thousands or millions of mentions. Both take the same filters and sort orders. Streams need the Enterprise tier.

#### Can I get a whole conversation thread?

Yes. Every mention row carries a `discussionId`. Put it into a discussion mode to read the post with all of its comments, or put a comment's ID into the parent mode to get the post it replies to.

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

No. It reads only. The search and stream calls are POST requests because the filters travel as a JSON body, but they change nothing. The project create, update and delete routes and the mention tag routes are not used. The key is never logged and is stripped from any error text.

#### How is it priced?

Pay per result: one price per mention and a lower price per project row. Requests that find nothing are free. Your SentiOne subscription and mentions cap apply separately.

### Example output

```json
{
  "mode": "recentMentions",
  "modeLabel": "Recent mentions",
  "recordType": "mention",
  "projectId": "12345",
  "discussionId": "fb-post-123456789012345",
  "found": true,
  "id": "smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48",
  "name": "Sarah Johnson",
  "publishedAt": "2025-05-16T10:09:48.000Z",
  "collectedAt": "2025-05-16T10:09:53.122Z",
  "mentionType": "Post",
  "sourceType": "Facebook",
  "sentiment": "Positive",
  "title": null,
  "text": "Apple is revolutionary!",
  "url": "https://www.facebook.com/posts/123456789012345",
  "authorName": "Sarah Johnson",
  "authorId": "facebook_user_1234567890",
  "authorGender": "Female",
  "followerCount": 245,
  "channelName": "Tech Reviews Hub",
  "channelId": "facebook_page_987654321",
  "language": "en",
  "country": null,
  "influenceScore": 8,
  "engagementRate": 0.125,
  "likeCount": 45,
  "shareCount": 12,
  "commentCount": 8,
  "viewCount": null,
  "ratingValue": null,
  "parentText": null,
  "tags": [],
  "sourceAttribution": "Source: sentione.com",
  "author": { "id": "facebook_user_1234567890", "name": "Sarah Johnson", "gender": "Female", "influenceMetrics": { "followerCount": 245, "fanCount": null } },
  "source": { "socialChannel": { "id": "facebook_page_987654321", "name": "Tech Reviews Hub" }, "mentionUrl": "https://www.facebook.com/posts/123456789012345", "type": "Facebook" },
  "content": { "text": "Apple is revolutionary!", "language": { "code": "en" }, "sentiment": "Positive" },
  "engagementMetrics": { "influenceScore": 8, "engagementRate": 0.125, "sourceMetrics": { "common": { "likeCount": 45, "shareCount": 12, "commentCount": 8 }, "facebook": { "likeCount": 45, "loveCount": 15, "hahaCount": 2, "wowCount": 3, "sadCount": 0, "angryCount": 1 } } },
  "attachments": [],
  "retrievedAt": "2026-10-05T09:14:52.118Z",
  "note": null
}
```

Values are illustrative and follow the provider's documented examples; every field is one the provider documents. Project rows carry `id` and `name`; parent rows also carry `childMentionId`.

### Keyword map

social listening API, social media monitoring API, brand mentions export, mentions API, sentiment analysis data, social media sentiment, online reputation monitoring, share of voice data, review monitoring, Facebook comments export, X (Twitter) mentions export, Reddit and forum monitoring, SentiOne API, SentiOne Listen API, SentiOne mentions export.

# Actor input Schema

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

Projects lists the Listen projects your key reaches and needs nothing else, so it is the default: it gives the project IDs the other modes use. Recent mentions pages through the last 7 days of one project (free Basic API tier). Historical mentions pages through any period (Enterprise tier). The two export stream modes read the same mentions as one fast stream for large volumes (Enterprise tier). The discussion modes read one thread, a post with its comments. The mention modes look mentions, or the post a comment replies to, up by ID.

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

Mention and export modes. The numeric ID of one Listen project, as the projects mode lists it. Optional when your key reaches only one project. In the projects mode it reads just that project.

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

Optional Listen Query Language filter on the mention text, up to 500 characters: AND, OR, NOT, parentheses, "exact phrases" and word\* wildcards (4 or more letters before the asterisk). Example: "customer service" AND (slow OR rude) NOT job\*

## `lastDays` (type: `integer`):

Read mentions from this many days back until now. Recent modes see at most 7 days. Ignored when a date start or end is set. Leave empty for the provider default (the last 7 days in recent modes, no time limit in historical modes).

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

Custom range start, inclusive, as YYYY-MM-DD or an ISO 8601 date-time such as 2026-09-01T00:00:00Z. Cannot be in the future.

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

Custom range end, exclusive, as an ISO 8601 date-time. A plain YYYY-MM-DD date includes that whole day.

## `timeField` (type: `string`):

Filter on when the mention was published, or on when SentiOne collected it (use this for incremental exports that never miss late arrivals).

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

Keep only mentions from these source types. Leave empty for all.

## `mentionTypes` (type: `array`):

Keep only these mention formats. Leave empty for all.

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

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

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

Keep only mentions in these languages, as two-letter ISO 639-1 codes such as en, pl or de. Leave empty for all.

## `sortType` (type: `string`):

The documented sort orders. Search and export modes.

## `discussionId` (type: `string`):

Discussion modes. The ID of one thread, exactly as the discussionId column of any mention row shows.

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

Mention modes. One mention ID per line, each starting with smid-, as the id column of any mention row shows. The parent mode returns the post or article each one replies to.

## `anonymize` (type: `string`):

Export stream modes only, an experimental provider feature. Author replaces author names and IDs with consistent hashes and drops avatars. All also hashes the channel and removes the location.

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

The most rows this run returns and charges for. Search modes read 25 mentions a call and the provider allows 30 search calls an hour, so use an export stream mode for more than about 700 mentions; streams are sent this number as their documented limit so they never spend your monthly mentions cap past it.

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

Your own Listen API key (V2), from Organization > API Access in the SentiOne app. It starts with S1-APIKEY-. Stored as a secret. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "projects",
  "lastDays": 7,
  "timeField": "publishedAt",
  "sortType": "PublishedAtDescending",
  "anonymize": "none",
  "maxResults": 100
}
```

# Actor output Schema

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

One row per mention or project.

# 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-export-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-export-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-export-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-export-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/OHr8IgwG2PuHmzLrM/builds/g7fNxc6nD65hb5CYs/openapi.json