# Brand Pulse: News & Social Monitor (`codepal/brand-pulse`) Actor

Monitor your brand and competitors across Google News (incl. African editions), Bing News, RSS feeds and TikTok/social datasets. Brand-level sentiment, risk flags, story clustering, share of voice, spike alerts and AI briefings.

- **URL**: https://apify.com/codepal/brand-pulse.md
- **Developed by:** [Jared Keanche](https://apify.com/codepal) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 new mentions

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

## Brand Pulse: News & Social Monitor

**Know what the media and social users are saying about your brand and competitors, and get alerted the moment a story turns negative.**

Brand Pulse tracks your brand in **Google News across country editions** (Kenya, Nigeria, South Africa, Ghana, Uganda, Tanzania, Rwanda, Ethiopia, Egypt, Francophone Africa, US, UK, India…), **Bing News**, any **RSS feed** and your **TikTok or other social datasets**. Media monitoring tools usually cost hundreds of dollars a month; this costs cents per day.

### What you get

- **Every mention**: outlet, headline, snippet, link, date, the entities it names (your brand and competitors), and whether it is new since the last run.
- **Sentiment about you, not about the article.** Sentences that name you are scored separately, so "Airtel grows while Safaricom faces backlash" counts as negative for Safaricom and positive for Airtel. Articles with direct links are opened and the paragraphs that mention you are analysed.
- **Risk flags**: legal & regulatory, security & fraud, outages & operations, financial, and reputation.
- **Topics**: launches, financial results, leadership, partnerships, regulation, customer experience, CSR, technology, expansion.
- **Stories**: the same news covered by many outlets is grouped into one story, with outlet count, major-outlet count, sentiment and impact score.
- **Share of voice** vs competitors, net sentiment, negative %, risk mentions, top outlets, top topics and mentions per day.
- **Spike detection**: last-24-hour volume vs your normal daily volume (history kept per monitor), plus negativity spikes.
- **Alerts** to Slack, Discord, Teams (via workflows) or any webhook. They cover volume spikes, negative spikes, new risk stories on major or multiple outlets, and viral negative social posts.
- **Optional AI briefing** with your own key: an executive summary, key stories, risks with recommended actions, a competitor watch and a holding statement when a risk is high.
- **HTML report** ready to forward to your comms team.

### TikTok and other social data

Run the **TikTok Sentiment & Trend Intelligence** Actor (or any X, Reddit, YouTube or Instagram scraper) and pass its dataset ID in *Social datasets*. Brand Pulse detects text, dates, engagement and existing sentiment labels automatically. Social mentions then appear alongside news in share of voice, alerts and the report. Chain both Actors with an Apify integration ("run Brand Pulse when the TikTok run succeeds") for a fully automatic pipeline.

### Example input

```json
{
  "brandName": "Safaricom",
  "brandAliases": ["M-Pesa", "SCOM"],
  "excludeTerms": ["Safaricom Stadium"],
  "competitors": ["Airtel|Airtel Money", "Telkom Kenya|Telkom"],
  "editions": ["KE", "UG", "TZ"],
  "includeAfricaFeeds": true,
  "socialDatasetIds": ["<your TikTok dataset id>"],
  "lookbackDays": 7,
  "monitorName": "safaricom-daily",
  "webhookUrl": "https://hooks.slack.com/services/…"
}
```

Schedule it hourly, daily or weekly with the same *Monitor name*. Spike baselines improve after a few runs, and each mention is charged only once.

### Output

- **Dataset**: the *Mentions* view, plus a *Negative & risk mentions* view.
- **REPORT** (HTML) · **STORIES** · **SHARE_OF_VOICE** · **OUTPUT** (spikes, alerts, AI briefing, per-source stats, warnings).

### Good to know

- Google News RSS links point to Google's redirect page and carry headlines only. Bing and publisher feeds give direct links and snippets, which allow article reading.
- Items that don't actually name a tracked entity are dropped (search engines return loose matches).
- Sentiment is lexicon-based (English plus common Swahili/Sheng), fast and explainable. Use the AI briefing for nuance.
- The built-in African feed list is best effort: a feed that moves or fails is skipped and reported in warnings.
- Social usernames are excluded unless you turn them on. Only public content is processed.

### Pricing

$1.50 per 1,000 new mentions, plus $0.01 per AI briefing (optional). See PRICING.md.

# Actor input Schema

## `brandName` (type: `string`):

The name the media uses for you.

## `brandAliases` (type: `array`):

Product names, short names, CEO or ticker (e.g. M-Pesa, SCOM). Short ALL-CAPS aliases match case-sensitively.

## `excludeTerms` (type: `array`):

Ignore false hits, e.g. a stadium or sports team named after you.

## `competitors` (type: `array`):

One per line; add aliases after a pipe, comma-separated: 'Airtel|Airtel Money,Airtel Kenya'.

## `editions` (type: `array`):

Two-letter codes. Each edition surfaces that country's local outlets: KE, NG, ZA, GH, UG, TZ, RW, ET, EG, MA, SN, CI, US, GB, IN…

## `useGoogleNews` (type: `boolean`):

Search Google News RSS in each edition (headlines from thousands of outlets).

## `useBingNews` (type: `boolean`):

Bing News RSS adds direct article links and snippets, which give better sentiment.

## `includeAfricaFeeds` (type: `boolean`):

Also scan a built-in list of African publisher feeds (TechCabal, Techpoint Africa, Disrupt Africa, Capital FM, Punch, Premium Times, BusinessDay, Mail & Guardian, The Africa Report, Africanews). Only items naming a tracked entity are kept.

## `feedUrls` (type: `array`):

Any publisher, blog, regulator or press-release feed. Only items naming a tracked entity are kept.

## `socialDatasetIds` (type: `array`):

Apify dataset IDs to merge, e.g. the output of the TikTok Sentiment & Trend Intelligence Actor or any X/Reddit/YouTube scraper. Text, date, engagement and existing sentiment are detected automatically.

## `maxSocialItems` (type: `integer`):

Upper limit read from each dataset.

## `lookbackDays` (type: `integer`):

Mentions published in the last N days.

## `fetchArticles` (type: `boolean`):

Open articles with direct links to analyse the paragraphs that mention you (more accurate sentiment).

## `maxArticles` (type: `integer`):

Per run.

## `maxMentions` (type: `integer`):

Upper limit of mentions saved per run (newest first).

## `onlyNew` (type: `boolean`):

For scheduled runs: save only mentions not seen by this monitor before. Metrics still use the whole window.

## `monitorName` (type: `string`):

Runs with the same name share history (spike baseline, seen mentions, alerts already sent).

## `alertOnRiskNews` (type: `boolean`):

Alert on new negative stories with legal, security, outage, financial or reputation risk on a major outlet or several outlets, and on viral negative social posts.

## `spikeFactor` (type: `number`):

Alert when the last 24 h has this many times the usual daily mentions (min 3 mentions).

## `webhookUrl` (type: `string`):

HTTPS URL for alerts (Slack/Discord formatted automatically; JSON for Zapier, Make, n8n, Teams workflows).

## `webhookSecret` (type: `string`):

Optional HMAC signature (x-signature-256).

## `enableAi` (type: `boolean`):

Executive summary, key stories, risks with recommended actions, competitor watch and a holding statement when needed. Uses your own API key.

## `aiBaseUrl` (type: `string`):

Any OpenAI-compatible API (OpenAI, OpenRouter, Groq, Together, DeepSeek, local Ollama…).

## `aiModel` (type: `string`):

Model name at your provider.

## `aiApiKey` (type: `string`):

Stored encrypted; billed by your provider.

## `brandContext` (type: `string`):

Optional: what you do, current campaigns or known issues, to sharpen the briefing.

## `includeSocialAuthors` (type: `boolean`):

Off by default. News article authors are always included.

## `proxyConfiguration` (type: `object`):

Turn on if news sources start refusing requests.

## Actor input object example

```json
{
  "brandName": "Safaricom",
  "brandAliases": [
    "M-Pesa"
  ],
  "competitors": [
    "Airtel|Airtel Money"
  ],
  "editions": [
    "KE"
  ],
  "useGoogleNews": true,
  "useBingNews": true,
  "includeAfricaFeeds": false,
  "maxSocialItems": 3000,
  "lookbackDays": 7,
  "fetchArticles": true,
  "maxArticles": 40,
  "maxMentions": 2000,
  "onlyNew": false,
  "monitorName": "default",
  "alertOnRiskNews": true,
  "spikeFactor": 2.5,
  "enableAi": false,
  "aiBaseUrl": "https://api.openai.com/v1",
  "aiModel": "gpt-4o-mini",
  "includeSocialAuthors": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `mentions` (type: `string`):

Every news and social mention with sentiment, risks, topics and impact.

## `report` (type: `string`):

KPIs, alerts, share of voice, top stories and negative mentions.

## `stories` (type: `string`):

Mentions grouped into stories covered by several outlets, ranked by impact.

## `shareOfVoice` (type: `string`):

Per-entity mentions, sentiment, risks, topics, outlets and daily volume.

## `summary` (type: `string`):

Spikes, alerts, AI briefing, sources and warnings.

# 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 = {
    "brandName": "Safaricom",
    "brandAliases": [
        "M-Pesa"
    ],
    "competitors": [
        "Airtel|Airtel Money"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("codepal/brand-pulse").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 = {
    "brandName": "Safaricom",
    "brandAliases": ["M-Pesa"],
    "competitors": ["Airtel|Airtel Money"],
}

# Run the Actor and wait for it to finish
run = client.actor("codepal/brand-pulse").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 '{
  "brandName": "Safaricom",
  "brandAliases": [
    "M-Pesa"
  ],
  "competitors": [
    "Airtel|Airtel Money"
  ]
}' |
apify call codepal/brand-pulse --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codepal/brand-pulse"
        }
    }
}
```

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/E0JjAqSMND4f9c9Jj/builds/VINW332gJtqDvkjeW/openapi.json