# Brand Monitoring Tool for Mentions & Sources | Launch 30% Off (`winningsolutions/brand-citation-summary`) Actor

Brand monitoring tool for one keyword. Returns mention volume, top domains, sentiment, countries, and languages. Optional URL sources. Web mention snapshot, not LLM platforms or NAP listings.

- **URL**: https://apify.com/winningsolutions/brand-citation-summary.md
- **Developed by:** [Winning Solutions](https://apify.com/winningsolutions) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.03305 / brand summary

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Brand Mention Monitor: Mention Volume and Top Domains for One Brand

A **brand monitoring tool** that returns mention volume and top domains for one brand name or domain. Enter your **keyword** once. The Actor turns that input into structured results automatically.

It returns **structured JSON** with **mention volume**, **top domains**, **sentiment**, **countries**, **languages**, and optional **URL sources**.

Designed for **SEO teams and agencies** that need mention volume and sources in one run, the Actor delivers a live web mention snapshot. Each run is a snapshot. No alerts. No market filter on the core lookup.

> ## Mention volume plus top domains
>
> **One keyword. One snapshot.**
>
> Enter a brand name or domain such as Nike or nike.com. The first dataset row shows **mentionVolume** and aggregate signals. Up to 20 **domain** rows follow with mention counts. **Domain rows belong to the brand summary price.**

### Use Cases

- **Monitor** mention volume for one brand in a single run
- **Check** top domains that mention a brand keyword
- **Export** optional URL source rows for editorial review
- **Compare** sentiment and country mix on the volume row
- **Feed** reporting pipelines with structured JSON rows

### Index

- [Release Notes](#release-notes)
- [Brand monitoring tool features](#brand-monitoring-tool-features)
- [Use Cases](#use-cases)
- [Pricing](#pricing)
- [Input](#input)
- [Input Example](#input-example-brand-keyword)
- [API and MCP usage](#api-and-mcp-usage)
- [Output Structure](#output-structure)
- [Output Example](#output-example)

### Release Notes

#### v0.0 - Initial public release

- **Mention volume row:** One volume row with mentionVolume, rank, sentiment, countries, and languages per keyword
- **Top domains:** Up to 20 domain rows with mention counts included in the brand summary price
- **Optional URL sources:** Enable includeSources to add charged URL source rows after the aggregate

### Brand monitoring tool features

✅ **Mention volume snapshot:** One volume row per keyword with mentionVolume, rank, and topDomainCount.

🌐 **Top domains:** Up to 20 domain rows with mentionCount and rankInList. Domain rows are not charged separately.

📄 **Optional URL sources:** Turn on includeSources to fetch URL source rows after the aggregate.

📊 **Sentiment breakdown:** sentimentConnotations and connotationTypes on the volume row.

🗺️ **Geography and language mix:** countries and languages objects on the volume row.

🔢 **One keyword per run:** Pass a brand name, domain, or URL. URLs become the host.

🚫 **No LLM prompt tracking:** Web mention aggregate only. Not AI answer monitoring.

⚠️ **Diagnostic rows:** Failed auth or upstream errors write a row with `_metadata.error` and no charge.

#### Optional URL sources

When enabled, the Actor fetches URL source rows after the volume and domain rows:

- **Include sources** (`includeSources`) - Add URL source rows after the mention volume. Charged as **mention-source** ($0.0330495 per row at launch, $33.0495 / 1,000 sources).
- **Max sources** (`maxSources`) - Cap URL rows from 1 to 1000. Default 10. Ignored when sources are off. Charged as **mention-source** ($0.0330495 per row at launch, $33.0495 / 1,000 sources).

Turn this on when you need individual URLs, not just the domain aggregate.

### Pricing

#### Launch pricing (until 2026-11-08)

| Cost item | Rate |
| --------- | ---- |
| Brand summary (1 volume row) | $0.0330495 |
| Mention source (1 URL row) | $0.0330495 |
| Per 1,000 brand summaries | $33.0495 / 1,000 summaries |
| Per 1,000 mention sources | $33.0495 / 1,000 sources |
| Actor start | $0.00005 (infrequent) |
| Apify platform compute (RAM/time) | Billed by Apify platform pricing |

#### Regular pricing (from 2026-11-08)

| Cost item | Rate |
| --------- | ---- |
| Brand summary (1 volume row) | $0.048072 |
| Mention source (1 URL row) | $0.048072 |
| Per 1,000 brand summaries | $48.072 / 1,000 summaries |
| Per 1,000 mention sources | $48.072 / 1,000 sources |
| Actor start | $0.00005 (infrequent) |
| Apify platform compute (RAM/time) | Billed by Apify platform pricing |

> **Launch cost per keyword: ~$0.0330995** - Default run with one keyword and sources off costs about $0.0330995 including actor start.

Domain rows stay in the brand-summary price. They add no extra event. You pay **mention-source** only for each URL source row when includeSources is true.

#### Free plan limit

Runs from Apify free plan accounts are limited to 0 source rows per run. The Actor keeps includeSources off and still runs the core lookup for one keyword.
The run finishes normally and keeps every result already written.

#### Cost Examples

Based on the launch prices above.

**Scenario A: Default run, sources off (1 keyword)**

- Actor start: $0.00005
- 1 brand summary: $0.0330495
- **Total: ~$0.0330995**

**Scenario B: Sources on, 10 URLs (schema default)**

- Actor start: $0.00005
- 1 brand summary: $0.0330495
- 10 mention sources: $0.330495
- **Total: ~$0.3635945**

**Scenario C: Sources on, 100 URLs**

- Actor start: $0.00005
- 1 brand summary: $0.0330495
- 100 mention sources: $3.30495
- **Total: ~$3.3380495**

### Input

The Actor accepts the following input parameters (see the **Input** tab in the Apify Console for the full, interactive schema):

| Parameter | Type | Required | Default | Description |
| --------- | ---- | -------- | ------- | ----------- |
| `keyword` | string | yes | none | Brand name or domain to look up. One value. A full URL becomes the host. Example: Nike or nike.com |
| `includeSources` | boolean | no | `false` | Add URL source rows after the mention volume. Default is off. Apify Free plan keeps this off. |
| `maxSources` | integer | no | `10` | Maximum URL source rows when sources are on. Range 1-1000. Default 10. Ignored when sources are off. Apify Free plan keeps sources off. |

#### Input Example (Brand keyword)

```json
{
  "keyword": "Nike"
}
```

### API and MCP usage

Runs write **one dataset row per result row** (volume, domain, or source).
Fetch rows from the default dataset after the run succeeds (or use the synchronous endpoint below).

**REST (sync, returns dataset items):** replace `YOUR_USERNAME`, `YOUR_API_TOKEN`, and use the same JSON body as in [Input Example](#input-example-brand-keyword).

```bash
curl "https://api.apify.com/v2/acts/YOUR_USERNAME~brand-citation-summary/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"keyword":"Nike"}'
```

**JavaScript (`apify-client`):**

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = {
  keyword: 'Nike',
};
const run = await client.actor('YOUR_USERNAME~brand-citation-summary').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**Apify MCP server (AI agents):** configure your MCP client with URL `https://mcp.apify.com?tools=YOUR_USERNAME~brand-citation-summary` (you can combine multiple tools per [Apify MCP docs](https://docs.apify.com/platform/integrations/mcp)). Pass the API token via your client (for example an `Authorization: Bearer ...` header), not inside the Actor input JSON.

### Output Structure

The Actor returns structured data for each result row. The table below lists the main fields. Rows use `rowType` values `volume`, `domain`, or `source`. Domain rows are not charged separately.

| Field | Type | Description | Example Value |
| ----- | ---- | ----------- | ------------- |
| `rowType` | string | Row kind: volume, domain, or source | `"volume"` |
| `keyword` | string | Cleaned input keyword | `"Nike"` |
| `mentionVolume` | number | Total mention count on the volume row | `4000000` |
| `mentionCount` | number | Same as mentionVolume on the volume row. Domain count on domain rows | `23552` |
| `rank` | number | Rank on the volume row | `523` |
| `topDomainCount` | number | Count of domain rows written | `20` |
| `domain` | string | Top domain on the volume row. Domain name on domain or source rows | `"nike.com"` |
| `mentionsPositive` | number | Positive mention count on the volume row | `1734144` |
| `mentionsNegative` | number | Negative mention count on the volume row | `1521760` |
| `mentionsNeutral` | number | Neutral mention count on the volume row | `495184` |
| `topCountry` | string | Country with the highest mention count | `"US"` |
| `topLanguage` | string | Language with the highest mention count | `"en"` |
| `rankInList` | number | Position in the top domain list | `1` |
| `url` | string | Source URL on source rows | `"https://example.com/a"` |
| `title` | string | null | Page title on source rows | `"Title"` |
| `snippet` | string | null | Text snippet on source rows | `"..."` |
| `sentimentConnotations` | object | Sentiment keys on volume or source rows | `{"anger":0,"happiness":1}` |
| `countries` | object | Top countries on the volume row | `{"US":100}` |
| `languages` | object | Top languages on the volume row | `{"en":100}` |
| `_metadata.resultCharged` | boolean | Whether this row was charged | `true` |
| `_metadata.error` | string | null | Present on failure or diagnostic rows | *(varies)* |
| `_metadata.errorContext` | string | null | Extra error context when `error` is set | *(varies)* |

#### Output Example

```json
{
  "rowType": "volume",
  "keyword": "Nike",
  "mentionVolume": 4000000,
  "mentionCount": 4000000,
  "rank": 523,
  "topDomainCount": 20,
  "domain": "nike.com",
  "mentionsPositive": 1734144,
  "mentionsNegative": 1521760,
  "mentionsNeutral": 495184,
  "topCountry": "US",
  "topLanguage": "en",
  "sentimentConnotations": {
    "anger": 0,
    "happiness": 1,
    "love": 0,
    "sadness": 0,
    "share": 0,
    "fun": 0
  },
  "connotationTypes": {
    "positive": 1,
    "negative": 0,
    "neutral": 0
  },
  "pageTypes": {
    "ecommerce": 100
  },
  "countries": {
    "US": 100
  },
  "languages": {
    "en": 100
  },
  "textCategories": [
    {
      "count": 10
    }
  ],
  "pageCategories": [
    {
      "count": 8
    }
  ],
  "_metadata": {
    "resultCharged": true,
    "error": null,
    "errorContext": null
  }
}
```

# Actor input Schema

## `keyword` (type: `string`):

Brand name or domain to look up. One value. A full URL becomes the host. Example: Nike or nike.com

## `includeSources` (type: `boolean`):

Add URL source rows after the mention volume. Default is off. Apify Free plan keeps this off.

## `maxSources` (type: `integer`):

Maximum URL source rows when sources are on. Range 1-1000. Default 10. Ignored when sources are off. Apify Free plan keeps sources off.

## Actor input object example

```json
{
  "keyword": "Nike",
  "includeSources": false,
  "maxSources": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "keyword": "Nike"
};

// Run the Actor and wait for it to finish
const run = await client.actor("winningsolutions/brand-citation-summary").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 = { "keyword": "Nike" }

# Run the Actor and wait for it to finish
run = client.actor("winningsolutions/brand-citation-summary").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 '{
  "keyword": "Nike"
}' |
apify call winningsolutions/brand-citation-summary --silent --output-dataset

```

## MCP server setup

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

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/cNdawtpW2acD4jaTP/builds/GjbhCrBhmOvx0j6hj/openapi.json