# Social Media Monitoring API - Mentions, Sentiment, Talkwalker (`nabeelbaghoor/social-media-monitoring-search-api`) Actor

Export social media monitoring data from your own Talkwalker account: mentions with sentiment, reach, engagement, author and country from projects or the global index, plus histograms, top influencers, topics, custom tags, export task results and credits. Read only. Bring your own token.

- **URL**: https://apify.com/nabeelbaghoor/social-media-monitoring-search-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 Media Monitoring API - Mentions, Sentiment, Talkwalker

Export the mentions, sentiment, reach and trend data your Talkwalker projects collect into a dataset, a spreadsheet or a warehouse, with one row per mention, histogram bin or influencer. Uses your own Talkwalker API token, never changes anything in your account, and charges only for rows that carry data.

### What it collects

- **Mentions (documents)** from any project, over its full history, or from the 30 day global index: URL, title, content and snippet, publication date, source type (online news, blogs, forums, X, YouTube and more), language, sentiment score, reach, engagement, author name, gender and profile, source site, country, region and city, matched topics, custom tags, hashtags, images and per network engagement counts.
- **Real Talkwalker query syntax**: boolean operators, `lang:`, `sourcetype:`, `published:>` and the other modifiers, plus the time range (`7d`, `3M`), timezone, sort field and order, highlighting, and the project topics, filters, channels, source panels and Customer Intelligence datasets.
- **Histograms**: mention volume over time by hour, day or week, optionally broken down by sentiment, source type, country, topic or channel, a nested metric such as engagement, and distributions by language, country, region, city, gender, age, themes, trending themes, hashtags, mentioned accounts, emoji, interests and occupations. Forecasts on projects that have them.
- **Top influencers**: the top 100 authors or sources of a project, ranked by mentions, sentiment, reach or engagement, with their network and matched topics.
- **Project setup**: topics and filters with their included and excluded queries, resource IDs (topics, filters, pages, events, panels) and custom tags.
- **Export results**: the status and progress of your export tasks, your streams and collectors, and the documents an export task has queued in a collector, with the resume offset for the next run.
- **Credit balance**: monthly and one-time credits used and remaining, the next billing date and six months of history.
- Read only, pay per result, bring your own token.

### Input

| Field | What it does |
| --- | --- |
| What to read | Projects (default, needs nothing else), search results, histogram, top influencers, topics and filters, project resources, custom tags, streams and collectors, export tasks, collector results or credit balance. |
| Project ID | Needed by top influencers, topics, resources and tags. Search results and histogram read the global index when it is empty. |
| Query | Talkwalker query syntax, such as `tesla AND "electric car" AND lang:en`. Required for the global index. |
| Topic, filter, channel, panel and dataset IDs | Narrow a project read to what is configured in it. The topics and resources modes list the IDs. |
| Time range, timezone | Search results. `30d`, `12h`, `2w`, `3M`. |
| Sort results by / Sort order | Engagement, published, reach, network metrics, cluster size, comment count, search_indexed or trending score. |
| Highlight matches | Bold the matched keywords in the snippets. |
| Histogram type, start, end, interval, breakdown, nested metric, top N, forecast days | Histogram mode. |
| Influencer type / Rank influencers by | Top influencers mode. |
| Resource type | Project resources mode. |
| Export task ID | Export tasks mode: one task, or all recent tasks when empty. |
| Collector ID / Resume offset | Collector results mode. |
| Maximum results | Row cap for the run. |
| Requests per minute | Pacing. |
| Access token | Your own Talkwalker API access token, as a secret input. |

Run the projects mode first, then topics with a project ID, then search results or histogram with the project ID and any topic IDs.

### Credits and limits on the Talkwalker side

Talkwalker meters its API in credits, separately from this actor's price:

- Search API: 1 credit per result returned, and at least 10 credits per call. This actor pages with up to 500 results per call so the minimum rarely applies.
- Histogram API: 10 credits per call, whatever the number of bins.
- Streaming and export: 1 credit per document pushed into a collector.
- Credits reset monthly on the subscription day. The credit balance mode costs nothing but is limited to 10 calls a minute.
- Rate limits: 60 search calls and 30 histogram calls a minute inside a project, 240 and 60 outside one.
- A project query returns at most 10,000 results (offset plus page size); the global index returns at most 500 and only the last 30 days.

### FAQ

#### What is a social media monitoring API used for?

Moving monitored conversation out of the Talkwalker dashboard and into your own tools. A brand team exports every negative mention from the last week with reach and author into a support queue. An agency pulls daily mention volume by sentiment for competitor topics into a client report. An analyst feeds Talkwalker documents into a warehouse to join with sales or campaign data. A comms team tracks top influencers and trending themes around a launch.

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

The Talkwalker API at api.talkwalker.com, through the routes documented at developer.talkwalker.com and in its published OpenAPI file: the Search API (project and global results), the Histogram API (project, global and top influencers), the Resources and Topic APIs (topics, resources, custom tags), the Streaming API (stream info and collector reads) and the Export Task API (task status), plus the credit status endpoint. Talkwalker is part of Hootsuite; its API host and developer portal were checked live on 2026-10-02.

#### Do I need a Talkwalker access token?

Yes. This actor is bring-your-own-token and never ships one. Talkwalker issues API access with an API application on paid plans; your account manager or administrator can give you the access token. Paste it into the input, or set it once as the `DATA_API_KEY` environment secret. A missing, inactive or refused token, and an account out of credits, each end the run cleanly with a message saying which it was.

#### How many mentions can one run export?

Up to 100,000 rows per run across modes. One project query returns at most 10,000 results under Talkwalker's paging rule, and the global index at most 500 from the last 30 days. For larger historical exports, create an export task in Talkwalker into a collector, then read it with the collector results mode; it streams the whole queue and logs a resume offset so the next run continues where this one stopped.

#### Why are some X, Facebook, Instagram or news mentions missing text?

Talkwalker's export rules, not this actor. Facebook and Instagram content cannot be exported at all (only aggregated metrics through the histogram mode), X posts are limited to the post ID, author ID and sentiment unless your account has the X data add-on, online news content is truncated to a snippet with the matched keywords highlighted, and LinkedIn, raw Reddit and raw TikTok documents are not exportable. Histograms still count all of them.

#### How do I get mention volume by sentiment per day?

Choose the histogram mode, type published, interval day and breakdown sentiment, with your project ID and optionally topic IDs. Each row is one day and one of POSITIVE, NEUTRAL or NEGATIVE, with the count in `value`. Net sentiment is (positive minus negative) divided by (positive plus negative).

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

No. Every call is a GET. The routes that create or delete topics, custom metrics, panels, streams, collectors and export tasks, and the document import and image upload routes, are not used. Talkwalker only accepts the token as a URL parameter; the actor never logs it, and strips it from any error text the provider echoes back.

#### How is it priced?

Pay per result: one price per mention, a lower price per analytics row (histogram bin or influencer) and per account record (project, topic, resource, tag, stream, task or credit balance). Requests that find nothing are free. Your Talkwalker subscription and credits apply separately.

### Example output

```json
{
  "mode": "search",
  "modeLabel": "Search results",
  "recordType": "document",
  "projectId": "a1ab1abc-a123-123a-123a-abcd12ab1a12",
  "found": true,
  "id": "https://www.example-news.com/2026/10/01/example-brand-recall",
  "name": "Jane Example",
  "date": "2026-10-01T08:14:30.000Z",
  "sentiment": -5,
  "sourceType": "ONLINENEWS, ONLINENEWS_OTHER",
  "country": "United States",
  "language": "en",
  "author": "Jane Example",
  "domain": "example-news.com",
  "url": "https://www.example-news.com/2026/10/01/example-brand-recall",
  "title": "Example Brand recalls its new charger",
  "snippet": "...the <b>Example Brand</b> recall affects chargers sold since June...",
  "reach": 7133333,
  "engagement": 2109,
  "matched_profile": ["kpnutesu_5imm9mo4lbsj"],
  "published": 1759306470000,
  "lang": "en",
  "source_type": ["ONLINENEWS", "ONLINENEWS_OTHER"],
  "tags_customer": ["Category / news"],
  "article_extended_attributes": { "facebook_shares": 220, "twitter_shares": 76 },
  "dimension1": null,
  "dimension2": null,
  "value": null,
  "totalHits": null,
  "retrievedAt": "2026-10-02T09:14:52.118Z",
  "note": null
}
```

Values are illustrative; every field is one the provider documents. Histogram rows carry `dimension1` (the time bin or the key, such as a country code), `dimension2` (the breakdown label) and `value`; influencer rows carry `posts`, `reach`, `engagement` and `sentimentBreakdown`.

### Keyword map

social media monitoring API, social listening API, brand mentions API, mentions export, media monitoring data, sentiment analysis data, share of voice, mention volume histogram, top influencers, trending themes, hashtag analytics, consumer intelligence API, Talkwalker API, Talkwalker search API, Talkwalker histogram API, Talkwalker export, Hootsuite Talkwalker data.

# Actor input Schema

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

Projects lists every project linked to your API application and needs nothing else, so it is the default. Search results read documents (mentions) from a project or, with no project ID, from the 30 day global index. Histogram counts documents over time or by a metric. Top influencers, topics and filters, project resources and custom tags read one project. Streams and collectors, export tasks and the credit balance read the account. Collector results read the documents an export task queued in a collector.

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

The Talkwalker project ID, as the projects mode lists it (for example a1ab1abc-a123-123a-123a-abcd12ab1a12). Needed by top influencers, topics, resources and tags. Optional for search results and histogram: without it they read the global index, which needs a query.

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

Search results, histogram and top influencers. A query in Talkwalker query syntax, such as tesla AND "electric car" AND lang:en, or sourcetype:ONLINENEWS AND published:>1727740800000. Optional in a project (the project topics apply), required for the global index.

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

Project modes. Keep only documents matching these topics, as the topics or resources mode lists them.

## `filterIds` (type: `array`):

Project modes. Apply these saved filters of the project.

## `channelIds` (type: `array`):

Project modes. Keep only documents from these channels of the project.

## `panelIds` (type: `array`):

Project modes. Keep only documents from these source panels of the project.

## `datasetIds` (type: `array`):

Project modes, Customer Intelligence projects only. Read these imported datasets. The provider cannot query datasets older than 7 days.

## `timeRange` (type: `string`):

Search results. How far back to read, as a number and a unit: s, m, h, d, w or M, such as 7d or 3M. The global index holds the last 30 days; a project holds its full history. Leave empty for the provider default.

## `timezone` (type: `string`):

Search results and histogram. A timezone name such as Europe/Luxembourg for the time range and time bins. Defaults to UTC.

## `sortBy` (type: `string`):

Search results. The documented sort fields. Defaults to engagement.

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

Search results. Descending or ascending.

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

Search results. Wrap matching keywords in bold tags in the title and content snippets.

## `histogramType` (type: `string`):

Histogram. published and search_indexed count documents over time; reach, engagement and the network metrics bin by value; language, country, gender, age, theme_cloud, hashtag, emoji and the others are distributions.

## `histogramMin` (type: `string`):

Histogram. The lowest bin, as YYYY-MM-DD or epoch milliseconds for time histograms. The provider defaults to the last 8 days.

## `histogramMax` (type: `string`):

Histogram. The highest bin (exclusive), as YYYY-MM-DD or epoch milliseconds.

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

Histogram. The bin size: a duration such as hour, day, 1w or 720d for published and search_indexed, or a number for value histograms. Not used by distributions.

## `breakdown` (type: `string`):

Histogram. Split each time bin by sentiment, source type or country, or in a project by topic or channel.

## `valueType` (type: `string`):

Histogram. Sum a metric such as engagement or reach inside each time bin, in addition to the count.

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

Histogram. How many values a distribution returns, such as the top 10 countries.

## `forecastDays` (type: `integer`):

Histogram in a project, published or search_indexed only, on projects with forecasting enabled. Days of forecast to add, 1 to 90.

## `influencerType` (type: `string`):

Top influencers. Authors or sources (sites and accounts).

## `influencerSort` (type: `string`):

Top influencers. Always descending. The provider returns up to 100.

## `resourceType` (type: `string`):

Project resources. Limit to one resource type.

## `taskId` (type: `string`):

Export tasks. Read one task by ID; leave empty to list all recent tasks.

## `collectorId` (type: `string`):

Collector results. The collector an export task or stream fills, as the streams mode lists it.

## `resumeOffset` (type: `string`):

Collector results. Where to start: earliest (the default), latest, or the resume offset a previous run logged.

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

The most rows this run returns and charges for. Search results page up to 500 at a time, up to 10,000 per project query and 500 in the global index.

## `requestsPerMinute` (type: `integer`):

Pacing. The provider allows 60 search calls and 30 histogram calls a minute in a project, and 10 a minute on the credit endpoint.

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

Your own Talkwalker API access token, from your Talkwalker API application. Stored as a secret. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "projects",
  "sortBy": "engagement",
  "sortOrder": "desc",
  "highlight": true,
  "histogramType": "published",
  "breakdown": "none",
  "influencerType": "author",
  "influencerSort": "total",
  "resourceType": "all",
  "maxResults": 100,
  "requestsPerMinute": 30
}
```

# Actor output Schema

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

One row per mention, histogram bin, influencer, topic, resource, tag, stream, export task or credit balance.

# 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-media-monitoring-search-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-media-monitoring-search-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-media-monitoring-search-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/social-media-monitoring-search-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/Z750VqQIuphGJAzNv/builds/Re0EeGs29BPhwSZpd/openapi.json