# Social Listening API - Brand24 Mentions, Sentiment, Topics (`nabeelbaghoor/social-listening-media-monitoring-api`) Actor

Social listening and media monitoring data from your own Brand24 projects: mentions filtered by date, sentiment and source, daily volume, reach and engagement, AI topics, spikes and summaries, influencers, domains, hashtags and demographics. Read only. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/social-listening-media-monitoring-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Social media, Marketing, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.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 - Brand24 Mentions, Sentiment, Topics

Pull the social listening and media monitoring data of your own Brand24 projects into a spreadsheet, warehouse or dashboard: every mention with its sentiment and source, daily volume, reach and engagement, AI topics, detected spikes, AI summaries, influencers, top domains, hashtags and audience demographics.

### What it collects

- **Mentions**: one row per mention with date, time, title, content (up to 250 characters), URL, host, source category, sentiment and your tags. Filter by date range, sentiment (positive, negative, neutral) and source category (news, blogs, web, podcasts, videos, TikTok, X, Facebook, Instagram, other social networks). Paged through with the provider's cursor, 500 at a time.
- **Daily mention volume, sentiment and reach**: one row per day with mention count, positive, negative and neutral counts, and social and non-social reach.
- **Daily metrics**: one row per day with mentions, reach, sentiment split and reach by sentiment, likes, comments, shares and advertising value equivalent (AVE), optionally for one source and with a per-source breakdown.
- **AI analysis**: AI-detected topics with reach, sentiment and share of voice; detected events (spikes) with peak mentions, peak reach and an AI description; the AI summary; AI insights.
- **Sources and people**: influential authors by followers or mentions with an influencer score filter, popular domains with visits and influence score, most active sites, trending links, trending hashtags, hot hours and audience demographics.
- **Setup**: project keywords, the projects of an account, and the account's projected mention usage for the billing period.
- Read only, pay per result, bring your own key.

### Input

| Field | What it does |
| --- | --- |
| What to read | Mentions (default), daily volume, daily metrics, AI topics, events, AI summary, AI insights, influential authors, popular domains, most active sites, trending links, trending hashtags, hot hours, demographics, project keywords, projects of an account, or projected usage. |
| Project ids | One Brand24 project id per line. |
| Account id | Projects only: the account whose projects to list. |
| Start date, End date | Date range as YYYY-MM-DD. Mentions and daily volume default to the last 30 days. Daily volume, daily metrics, AI summary and AI insights allow at most 31 days. |
| Sentiment | Mentions only: positive, negative and or neutral. |
| Source categories | Mentions only: news, blogs, web, podcasts, videos, TikTok, X, Facebook, Instagram, other social networks. |
| Metrics source, Per-source breakdown | Daily metrics only. |
| Event order | Detected events only: newest or oldest first. |
| Author order, Minimum influencer score | Influential authors only. |
| Maximum results | Row cap for the run. |
| Requests per minute | Pacing for calls to the provider. |
| API key | Your own Brand24 API Data key, as a secret input. |

### Example output

A mention:

```json
{
  "service": "mentions",
  "serviceLabel": "Mentions",
  "requested": "123456789",
  "found": true,
  "projectId": "123456789",
  "dateFrom": "2026-09-01",
  "dateTo": "2026-09-30",
  "date": "2026-09-27",
  "time": "14:32",
  "title": "Acme launches its new trail running shoe",
  "content": "Acme today announced a lighter trail running shoe aimed at ultra runners, with a recycled upper and...",
  "url": "https://news.example.com/acme-trail-shoe",
  "tweetId": null,
  "host": "news.example.com",
  "category": "news",
  "sentiment": "positive",
  "sentimentScore": 1,
  "tags": ["launch"],
  "retrievedAt": "2026-10-01T09:14:52.118Z",
  "note": null
}
```

A day of daily metrics:

```json
{
  "service": "dailyMetrics",
  "projectId": "123456789",
  "date": "2026-09-27",
  "mentionsCount": 320,
  "reach": 540000,
  "positiveMentions": 112,
  "negativeMentions": 64,
  "neutralMentions": 144,
  "likes": 2100,
  "comments": 340,
  "shares": 95,
  "ave": 12345.6,
  "sentimentShare": { "positive": 0.35, "neutral": 0.45, "negative": 0.2 }
}
```

Values are illustrative.

### FAQ

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

Moving brand monitoring data out of Brand24 and into the tools a team already uses. A PR team exports every negative news and blog mention of the week into Google Sheets for triage. A marketing analyst loads daily mentions, reach, engagement and AVE into BigQuery or Looker Studio to report share of voice. A brand manager tracks spikes, AI topics and the most influential authors after a product launch. An agency pulls the AI summary of each client project into a monthly report.

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

The Brand24 API Data service at api-data.brand24.com, through the read routes of its public OpenAPI documentation at api-data.brand24.com/api-data-docs/documentation: projects list, mentions, mention count, sentiment and reach, daily metrics, project events, topics, AI summary, AI insights, domains, trending links, trending hashtags, demographics, most active sites, hot hours, most followers, keywords and mentions usage estimation. The one documented write, create project, is not used.

#### Do I need a Brand24 account and API key?

Yes. This actor is bring-your-own-key and never ships one. It reads projects that already exist in your Brand24 account, with the API Data key shown at app.brand24.com/account/integrations-api-data. Paste it into the input, or set it once as the `DATA_API_KEY` environment secret. It is sent only in the `X-Api-Key` header to the API host. A missing or refused key ends the run cleanly with a message saying which it was.

#### Can it monitor a keyword or brand that is not set up in Brand24?

No. The provider's API reads the projects you have set up in the Brand24 web app, with their keywords. To monitor a new brand or keyword, create a project in Brand24 first, then read it here.

#### Why are some Facebook, Instagram and X mentions missing their text?

The provider blanks them under those platforms' terms. Facebook and Instagram mentions come without title, content and URL; X mentions come with the tweet id in `tweetId`. Date, host, category, sentiment and tags are always present.

#### How do I find my project ids?

Pick the projects service and enter your account id: it returns every project id and name in the account. Then put the project ids, one per line, into the project ids input.

#### What happens when a project has no data?

It becomes its own row with `found: false` and a note: no mentions in the range, topic analysis not enabled, or a project id the key cannot see. Those rows are never charged.

#### How is it priced?

Pay per result. Each mention is one price; each analytics record (a day of metrics, a topic, event, insight, author, domain, link, hashtag, hot hour, demographics profile, keyword set, project or usage forecast) is another. Rows for project ids that produced nothing are free. Your Brand24 subscription applies separately.

### Pricing

| Event | Price |
| --- | --- |
| Mention returned | $0.005 per mention |
| Analytics record returned | $0.01 per record |

### Keyword map

social listening API, media monitoring API, brand monitoring API, brand mentions export, mention tracking, sentiment analysis data, share of voice, online reputation monitoring, influencer discovery, hashtag tracking, news monitoring, PR monitoring, Brand24 API, Brand24 mentions export, Brand24 API Data.

# Actor input Schema

## `service` (type: `string`):

Mentions (the default) returns every mention of a project in the date range, with the sentiment and source filters below. The other project services return daily volume, sentiment and reach; daily metrics with engagement and AVE; AI topics, detected events, the AI summary and AI insights; influential authors, popular domains, most active sites, trending links and hashtags, hot hours, demographics and project keywords. Projects lists the projects of an account id, which is where project ids come from. Projected mentions usage needs nothing else.

## `projectIds` (type: `array`):

One Brand24 project id per line, as a number. Every service except projects and projected mentions usage reads them. The projects service lists the ids and names of every project in an account.

## `accountId` (type: `string`):

Projects only: the number of the Brand24 account whose projects to list.

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

First day of the range, as YYYY-MM-DD, inclusive. Mentions and daily volume need a range, so when both dates are empty they read the last 30 days. Other services send the date only when it is set and otherwise use the provider's default of about the last 30 days. Daily volume, daily metrics, AI summary and AI insights allow at most 31 days.

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

Last day of the range, as YYYY-MM-DD, inclusive. Defaults to today where a range is needed.

## `sentiment` (type: `array`):

Mentions only: keep mentions with these sentiments. Leave empty for all.

## `sourceCategories` (type: `array`):

Mentions only: keep mentions from these source categories. Leave empty for all. Facebook and Instagram mentions come without title, content or URL, and X mentions come with the tweet id only, because of those platforms' terms.

## `metricsSource` (type: `string`):

Daily metrics only: limit the totals to one source.

## `includeBySource` (type: `boolean`):

Daily metrics only: add a per-source breakdown of each day under bySource.

## `eventSortOrder` (type: `string`):

Detected events only: newest first or oldest first.

## `influencerSortBy` (type: `string`):

Influential authors only: rank by follower count or by number of mentions.

## `minInfluencerScore` (type: `integer`):

Influential authors only: keep authors with at least this influencer score, from 0 to 10.

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

Stop after this many rows across all projects.

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

Pacing ceiling for calls to the provider. Rate limited answers are retried after a pause.

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

Your own Brand24 API Data key, shown at app.brand24.com/account/integrations-api-data. This actor is bring-your-own-key and never ships one. Leave blank to use the DATA\_API\_KEY environment secret. The key is sent only in the X-Api-Key header to the API host, and is never written to a row or logged.

## `baseUrl` (type: `string`):

Override the host the actor calls. Only useful for testing against a different environment.

## Actor input object example

```json
{
  "service": "mentions",
  "metricsSource": "any",
  "includeBySource": false,
  "eventSortOrder": "desc",
  "influencerSortBy": "followers_count",
  "maxResults": 1000,
  "requestsPerMinute": 60
}
```

# Actor output Schema

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

One row per mention, daily metric, topic, event, insight, author, domain, link, hashtag 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-media-monitoring-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-media-monitoring-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-media-monitoring-api --silent --output-dataset

```

## MCP server setup

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