# Brand Sentiment Analyzer — Multi-Source Mentions + AI (`khadinakbar/brand-sentiment-analyzer`) Actor

Monitor brand sentiment across Reddit, Google News, and Trustpilot. Returns an executive summary with sentiment score, top complaints, top praise, crisis signals, and share-of-voice vs an optional competitor — plus per-mention details. AI theme extraction via Claude.

- **URL**: https://apify.com/khadinakbar/brand-sentiment-analyzer.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Marketing, AI, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 brand mention collecteds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Sentiment Analyzer — Multi-Source Mentions + AI Insights

**Monitor brand sentiment across Reddit, Google News, and Trustpilot in one run.** Get an executive summary with a brand health score, top complaints, top praise, crisis signals, and share-of-voice vs an optional competitor — plus per-mention details with individual sentiment classification. AI-powered theme extraction via Anthropic Claude.

Built as a drop-in replacement for [Brand24](https://brand24.com) (~$79+/mo), [Mention](https://mention.com) (~$41+/mo), and [Meltwater](https://meltwater.com) ($5K-$24K/yr). Pay only for what you run — typical brand report is ~$0.80.

### What this Actor does

You give it a brand name (e.g., `OpenAI`, `Tesla`, `Apify`). It:

1. Searches **Reddit** (posts + comments mentioning the brand)
2. Searches **Google News** (articles published about the brand)
3. Searches **Trustpilot** (customer reviews of the brand)
4. Aggregates and deduplicates the mentions
5. Sends them to **Claude AI** for theme extraction, complaint clustering, and crisis signal detection
6. Outputs one **executive summary** + **N raw mentions** with individual sentiment

Optionally, it does the same for a **competitor brand** and computes share-of-voice + sentiment delta.

Twitter/X and YouTube comment sources are reserved for v1.1.

### Why use this Actor

- **Replaces $79+/mo brand-monitoring SaaS** — pay only when you run a report
- **AI-powered insights** — not just "60% positive / 40% negative" (lexicon junk), but real themes like *"customers complain about late Black Friday delivery"*
- **Crisis detection** — flags boycott calls, lawsuits, viral negative posts, safety/regulatory concerns
- **Share-of-voice** — head-to-head sentiment comparison with a competitor in one run
- **MCP-ready for AI agents** — Claude/GPT/Gemini can call this actor via Apify MCP for real-time brand-reputation context
- **No API keys to manage** — Claude API runs server-side; you just provide the brand name

### How to use it

1. Open the [Apify Console](https://console.apify.com) and find this Actor.
2. Enter your brand name in the **Brand name or keyword** field.
3. (Optional) Add a competitor brand for share-of-voice comparison.
4. (Optional) Adjust mentions-per-platform (default 25) and time window (default 7 days).
5. Click **Start**.
6. Read the summary (first dataset record) — get the brand health score, top complaints, top praise, crisis signals, and executive summary at a glance.
7. Drill into the per-mention data for evidence and source URLs.

Typical run: ~30-60 seconds, ~$0.80 per brand report.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `brandName` | string | (required) | Brand or keyword to monitor (e.g., `"OpenAI"`, `"Tesla"`) |
| `competitorBrand` | string | `""` | Optional competitor for share-of-voice comparison |
| `platforms` | array | `["reddit", "google-news", "trustpilot"]` | Sources to monitor |
| `maxMentionsPerPlatform` | int | `25` | Hard cap per source (5-500) |
| `timeRange` | enum | `"7d"` | `24h`, `7d`, `30d`, or `all` |
| `language` | enum | `"en"` | ISO 639-1 code (en/es/de/fr/pt/it/ja) or `all` |
| `includeAiInsights` | bool | `true` | Run Claude for themes + crisis signals (adds $0.30) |
| `responseFormat` | enum | `"detailed"` | `concise` (~80 tokens/item, agent-friendly) or `detailed` |
| `maxCostUsd` | int | `0` | Hard cost cap; 0 = no cap |

#### Example input

```json
{
  "brandName": "Apify",
  "competitorBrand": "Bright Data",
  "platforms": ["reddit", "google-news", "trustpilot"],
  "maxMentionsPerPlatform": 30,
  "timeRange": "7d",
  "language": "en",
  "includeAiInsights": true,
  "responseFormat": "detailed"
}
````

### Output

The dataset contains:

- **One summary record** (first item, `_summary: true`) — executive analysis
- **Many mention records** (`recordType: "mention"`) — individual mentions with per-mention sentiment

You can download the dataset in JSON, CSV, HTML, or Excel. The full summary is also saved as a standalone file in the key-value store under `summary-<brand>-<timestamp>`.

#### Example summary record

```json
{
  "_summary": true,
  "recordType": "summary",
  "brandName": "Apify",
  "competitorBrand": "Bright Data",
  "brandHealthScore": 7.4,
  "sentimentBreakdown": {
    "positive": 42, "neutral": 28, "negative": 20,
    "positivePercent": 46.7, "negativePercent": 22.2
  },
  "topComplaints": [
    { "theme": "Pricing confusion", "frequency": 6,
      "exampleQuote": "Took me 30 minutes to figure out how compute units work" },
    { "theme": "Cold-start latency", "frequency": 4,
      "exampleQuote": "First run takes 90s before the actor even starts" }
  ],
  "topPraise": [
    { "theme": "MCP integration", "frequency": 14,
      "exampleQuote": "Apify MCP is the cleanest way to give Claude scraping superpowers" },
    { "theme": "Crawlee quality", "frequency": 11,
      "exampleQuote": "Crawlee handles anti-bot stuff that took us months to build in-house" }
  ],
  "crisisSignals": [],
  "shareOfVoice": {
    "brandMentions": 90, "competitorMentions": 64,
    "brandSharePercent": 58.4, "brandSentimentDelta": 1.8
  },
  "executiveSummary": "Apify is in healthy positive territory (7.4/10), driven by strong developer enthusiasm for MCP integration and Crawlee. Two friction points stand out: pricing transparency and cold-start latency. No crisis signals. Apify holds 58% share-of-voice vs Bright Data with a +1.8 sentiment lead.",
  "mentionCounts": { "twitter": 0, "reddit": 38, "youtube": 0, "googleNews": 27, "trustpilot": 25, "total": 90 },
  "warnings": [],
  "scrapedAt": "2026-05-03T14:00:00.000Z"
}
```

#### Example mention record

```json
{
  "recordType": "mention",
  "brandName": "Apify",
  "platform": "reddit",
  "sourceUrl": "https://www.reddit.com/r/webscraping/comments/...",
  "author": "scrape_dev_42",
  "text": "Apify MCP changed how I integrate scrapers with Claude — finally stable.",
  "title": "Apify MCP review after 3 months",
  "publishedAt": "2026-05-01T09:23:00.000Z",
  "engagement": { "score": 87, "comments": 14, "subreddit": "webscraping" },
  "sentiment": "positive",
  "sentimentScore": 0.78,
  "scrapedAt": "2026-05-03T14:00:00.000Z"
}
```

### Data fields

| Field | Where | Description |
|---|---|---|
| `recordType` | both | `summary` or `mention` |
| `brandHealthScore` | summary | 0–10 overall sentiment score |
| `sentimentBreakdown` | summary | counts + % positive/negative |
| `topComplaints` | summary | top 5 negative themes (Claude) |
| `topPraise` | summary | top 5 positive themes (Claude) |
| `crisisSignals` | summary | boycott/lawsuit/safety risks (Claude) |
| `shareOfVoice` | summary | mention-share + sentiment delta vs competitor |
| `executiveSummary` | summary | 3–5 sentence narrative (Claude) |
| `mentionCounts` | summary | per-source mention counts |
| `platform` | mention | `reddit`, `google-news`, `trustpilot` |
| `sourceUrl` | mention | direct link to mention |
| `text` | mention | full mention text |
| `sentiment` | mention | `positive` / `neutral` / `negative` |
| `sentimentScore` | mention | -1.0 to +1.0 |
| `engagement` | mention | platform-specific (score/rating/source) |
| `publishedAt` | mention | ISO 8601 |

### Pricing — How much does it cost to monitor a brand?

This Actor uses **Apify pay-per-event** pricing. You only pay for what you actually use:

| Event | Price | Description |
|---|---|---|
| `apify-actor-start` | $0.005 | Once per run (covers orchestration overhead) |
| `mention-found` | $0.005 | Per mention pushed to dataset |
| `ai-insights-generated` | $0.30 | Once per run when AI report is generated |

**Typical run cost** (3 sources × 25 mentions = 75 mentions + AI report):
`0.005 + (75 × 0.005) + 0.30 = $0.68 per brand report`

**Comparison:**

- Brand24: $79+/mo for ~2K mentions = $0.04/mention (no AI summary)
- Mention.com: $41+/mo for 250 mentions = $0.16/mention (no AI summary)
- This actor: $0.005/mention + AI = up to **30× cheaper per mention** with deeper analysis

Within the [x402 agent-payment](https://x402.org) prepay limit of $1, so AI agents can call this actor on demand.

### Tips & advanced options

- **Crisis monitoring** — set `timeRange: "24h"` and schedule the actor every 4 hours. AI flags boycotts and lawsuits in `crisisSignals`.
- **Launch tracking** — set `timeRange: "7d"` and run daily after launch.
- **Steady-state brand health** — set `timeRange: "30d"` and run weekly.
- **Lower cost** — set `includeAiInsights: false` to skip the $0.30 AI report and rely on lexicon-based per-mention sentiment only.
- **Compact agent output** — set `responseFormat: "concise"` to drop heavy fields; ~80 tokens/mention vs 250.
- **Cost cap** — set `maxCostUsd: 5` to guarantee no run exceeds $5.

### FAQ, disclaimers, and support

**Is brand monitoring legal?**
Yes — this actor only queries publicly indexed data (Reddit JSON search, Google News RSS, Trustpilot's public review pages). It does not bypass authentication walls. Users are responsible for compliance with their own jurisdiction's data-protection rules.

**Why aren't Twitter and YouTube included yet?**
Twitter/X requires either authenticated scrapers or paid API access; we're integrating it via `Actor.call` to a vetted X scraper in v1.1. YouTube requires a 2-step pipeline (search videos → scrape comments), planned for the same release.

**What if Trustpilot doesn't have my brand?**
The Trustpilot adapter resolves brand names to Trustpilot business slugs (e.g., `amazon` → `amazon.com`). If no business unit is found, it returns 0 mentions for that source — Reddit and Google News continue normally. Note: Trustpilot uses Cloudflare bot management which blocks non-browser TLS fingerprints on many brand pages — coverage is best for indie / smaller brands and may fail for major retailers (Amazon, Apple, etc.). v1.3 will add browser-fingerprint scraping for full Trustpilot coverage.

**What if Claude is unavailable?**
The actor falls back to lexicon-based per-mention sentiment scoring. The summary record will still ship with `brandHealthScore`, `sentimentBreakdown`, and an `executiveSummary` derived from the lexicon counts. AI-only fields (`topComplaints`, `topPraise`, `crisisSignals`) will be `null` and a warning will be added.

**Can I run this on a schedule?**
Yes. Use the Apify [Schedules](https://docs.apify.com/platform/schedules) feature to run daily/hourly. Set a `maxCostUsd` cap to avoid surprise bills.

**Found a bug or want a new source?**
Use the [Issues tab](../issues) on this Actor's page. Custom integrations available — DM the developer.

***

Built by [khadinakbar](https://apify.com/khadinakbar) — see the [full portfolio of 50+ data actors](https://apify.com/khadinakbar).

# Actor input Schema

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

The brand, product, or keyword to monitor. Used as a search query across all enabled sources. Examples: 'OpenAI', 'Tesla', 'iPhone 17 Pro', 'Apify'. Use exact spelling for best precision. NOT a profile URL or social handle — for those, use the platform-specific scrapers.

## `competitorBrand` (type: `string`):

An optional second brand to monitor in parallel for share-of-voice comparison. The AI summary will include side-by-side mention counts and sentiment splits. Example: if brandName is 'Apify', set this to 'Bright Data'. Leave empty to skip competitor analysis.

## `platforms` (type: `array`):

Default 3 sources (Reddit, Google News, Trustpilot) are scraped directly via public endpoints — fast and reliable. 'twitter' and 'youtube' are reserved for v1.3 and will return empty with a notice if selected. Cost scales linearly per platform — disable any you don't need. Each mention costs $0.005.

## `maxMentionsPerPlatform` (type: `integer`):

Hard cap on how many mentions to pull from each source. Default 25 keeps a typical run under $1. Set higher for deeper analysis (e.g., 100 for a comprehensive report). Total mentions across all platforms ≤ this number × number of platforms. Each mention costs $0.005.

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

How far back to search for mentions. '24h' for crisis monitoring, '7d' for launch tracking, '30d' for steady-state brand health, 'all' for historical analysis. Note: not every source supports every range — older content may be sparse on some platforms.

## `language` (type: `string`):

Two-letter language code (ISO 639-1). Filters mentions to this language only. Use 'en' for English, 'es' for Spanish, 'de' for German, 'fr' for French, 'all' for no filter. Default 'en'. Affects search query construction and sentiment-analysis quality.

## `includeAiInsights` (type: `boolean`):

If true (default), runs Claude Haiku over collected mentions to produce: brand health score (0-10), sentiment breakdown, top 5 complaints, top 5 praise themes, crisis signals, and executive summary. Adds $0.30 to run cost. Set false to get raw mentions only with lexicon-based per-mention sentiment.

## `responseFormat` (type: `string`):

'concise' returns short mention text + sentiment label only (~80 tokens/item — best for AI agents). 'detailed' returns full text, author, engagement metrics, URLs, and individual sentiment confidence (~250 tokens/item — best for analytics dashboards). Default 'detailed'.

## `maxCostUsd` (type: `integer`):

Hard spending cap per run. Actor stops gracefully when reached. Useful for bulk/scheduled runs to avoid surprise bills. Leave at 0 for no cap. Example: 5 means actor stops after spending $5. Recommended: set this to 2-3x your typical run cost as a safety net.

## Actor input object example

```json
{
  "brandName": "Apify",
  "competitorBrand": "",
  "platforms": [
    "reddit",
    "google-news",
    "trustpilot"
  ],
  "maxMentionsPerPlatform": 25,
  "timeRange": "7d",
  "language": "en",
  "includeAiInsights": true,
  "responseFormat": "detailed",
  "maxCostUsd": 0
}
```

# Actor output Schema

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

The standalone summary record saved as a JSON file in the key-value store. Open the run's key-value store, look for the 'summary-<brand>-<timestamp>' file.

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

The full dataset: first record is the executive summary (recordType=summary), followed by individual mentions (recordType=mention). Download as JSON, CSV, HTML, or Excel.

## `consoleRun` (type: `string`):

Apify Console run page with logs, stats, and timeline.

# 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": "Apify",
    "platforms": [
        "reddit",
        "google-news",
        "trustpilot"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/brand-sentiment-analyzer").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": "Apify",
    "platforms": [
        "reddit",
        "google-news",
        "trustpilot",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/brand-sentiment-analyzer").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": "Apify",
  "platforms": [
    "reddit",
    "google-news",
    "trustpilot"
  ]
}' |
apify call khadinakbar/brand-sentiment-analyzer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=khadinakbar/brand-sentiment-analyzer",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Brand Sentiment Analyzer — Multi-Source Mentions + AI",
        "description": "Monitor brand sentiment across Reddit, Google News, and Trustpilot. Returns an executive summary with sentiment score, top complaints, top praise, crisis signals, and share-of-voice vs an optional competitor — plus per-mention details. AI theme extraction via Claude.",
        "version": "1.5",
        "x-build-id": "ldK4DjGw7MYVo4UaY"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/khadinakbar~brand-sentiment-analyzer/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-khadinakbar-brand-sentiment-analyzer",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/khadinakbar~brand-sentiment-analyzer/runs": {
            "post": {
                "operationId": "runs-sync-khadinakbar-brand-sentiment-analyzer",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/khadinakbar~brand-sentiment-analyzer/run-sync": {
            "post": {
                "operationId": "run-sync-khadinakbar-brand-sentiment-analyzer",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "brandName"
                ],
                "properties": {
                    "brandName": {
                        "title": "Brand name or keyword",
                        "type": "string",
                        "description": "The brand, product, or keyword to monitor. Used as a search query across all enabled sources. Examples: 'OpenAI', 'Tesla', 'iPhone 17 Pro', 'Apify'. Use exact spelling for best precision. NOT a profile URL or social handle — for those, use the platform-specific scrapers.",
                        "default": "Apify"
                    },
                    "competitorBrand": {
                        "title": "Competitor brand (optional)",
                        "type": "string",
                        "description": "An optional second brand to monitor in parallel for share-of-voice comparison. The AI summary will include side-by-side mention counts and sentiment splits. Example: if brandName is 'Apify', set this to 'Bright Data'. Leave empty to skip competitor analysis.",
                        "default": ""
                    },
                    "platforms": {
                        "title": "Sources to monitor",
                        "type": "array",
                        "description": "Default 3 sources (Reddit, Google News, Trustpilot) are scraped directly via public endpoints — fast and reliable. 'twitter' and 'youtube' are reserved for v1.3 and will return empty with a notice if selected. Cost scales linearly per platform — disable any you don't need. Each mention costs $0.005.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "reddit",
                                "google-news",
                                "trustpilot",
                                "twitter",
                                "youtube"
                            ],
                            "enumTitles": [
                                "Reddit (live)",
                                "Google News (live)",
                                "Trustpilot reviews (live — limited)",
                                "Twitter / X (v1.3 — coming soon)",
                                "YouTube comments (v1.3 — coming soon)"
                            ]
                        },
                        "default": [
                            "reddit",
                            "google-news",
                            "trustpilot"
                        ]
                    },
                    "maxMentionsPerPlatform": {
                        "title": "Max mentions per platform",
                        "minimum": 5,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Hard cap on how many mentions to pull from each source. Default 25 keeps a typical run under $1. Set higher for deeper analysis (e.g., 100 for a comprehensive report). Total mentions across all platforms ≤ this number × number of platforms. Each mention costs $0.005.",
                        "default": 25
                    },
                    "timeRange": {
                        "title": "Time window",
                        "enum": [
                            "24h",
                            "7d",
                            "30d",
                            "all"
                        ],
                        "type": "string",
                        "description": "How far back to search for mentions. '24h' for crisis monitoring, '7d' for launch tracking, '30d' for steady-state brand health, 'all' for historical analysis. Note: not every source supports every range — older content may be sparse on some platforms.",
                        "default": "7d"
                    },
                    "language": {
                        "title": "Language filter",
                        "enum": [
                            "en",
                            "es",
                            "de",
                            "fr",
                            "pt",
                            "it",
                            "ja",
                            "all"
                        ],
                        "type": "string",
                        "description": "Two-letter language code (ISO 639-1). Filters mentions to this language only. Use 'en' for English, 'es' for Spanish, 'de' for German, 'fr' for French, 'all' for no filter. Default 'en'. Affects search query construction and sentiment-analysis quality.",
                        "default": "en"
                    },
                    "includeAiInsights": {
                        "title": "Generate AI insights report",
                        "type": "boolean",
                        "description": "If true (default), runs Claude Haiku over collected mentions to produce: brand health score (0-10), sentiment breakdown, top 5 complaints, top 5 praise themes, crisis signals, and executive summary. Adds $0.30 to run cost. Set false to get raw mentions only with lexicon-based per-mention sentiment.",
                        "default": true
                    },
                    "responseFormat": {
                        "title": "Response detail level",
                        "enum": [
                            "concise",
                            "detailed"
                        ],
                        "type": "string",
                        "description": "'concise' returns short mention text + sentiment label only (~80 tokens/item — best for AI agents). 'detailed' returns full text, author, engagement metrics, URLs, and individual sentiment confidence (~250 tokens/item — best for analytics dashboards). Default 'detailed'.",
                        "default": "detailed"
                    },
                    "maxCostUsd": {
                        "title": "Max cost ceiling (USD)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Hard spending cap per run. Actor stops gracefully when reached. Useful for bulk/scheduled runs to avoid surprise bills. Leave at 0 for no cap. Example: 5 means actor stops after spending $5. Recommended: set this to 2-3x your typical run cost as a safety net.",
                        "default": 0
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
