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

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