# Brand mention monitoring (/docs/recipes/brand-mention-monitoring)



Brand mention monitoring [#brand-mention-monitoring]

Build the core loop of a social listening tool: every day (or hour), find every new post mentioning your brand across the social web, skip what you've already seen, and surface the rest to Slack, email, or a dashboard.

How do you track brand mentions with an API? [#how-do-you-track-brand-mentions-with-an-api]

Call `GET /v1/search/everywhere` with your brand name and a short `lookback_days` window. The endpoint fans out across Reddit, X, YouTube, TikTok, Instagram, Hacker News, Polymarket, GitHub, Threads, Pinterest, LinkedIn, Rumble, Perplexity, and Tavily in parallel, returning every recent mention ranked and clustered — with each post's top comments attached — for a flat 20 credits.

The problem [#the-problem]

Brand mentions are scattered: a complaint thread on Reddit, a viral dunk on X, a review video on YouTube, a TikTok no one on your team would ever find. Social listening suites charge four figures a month for this sweep; building it yourself means integrating a dozen platform APIs with a dozen auth models.

The solution [#the-solution]

One universal search endpoint plus a tiny dedupe layer:

* `GET /v1/search/everywhere` — universal social search across 14 platforms, up to 17 sources (20 credits flat). Params: `query` (required), `lookback_days`, `from_date` / `to_date`, `sources`, `exclude`.

For platforms where you want deeper, targeted coverage, the per-platform search endpoints are standard tier (1 credit each) — `GET /v1/tiktok/search`, `GET /v1/reddit/search`, and `GET /v1/youtube/search` all take a `query` param and return full platform-native result lists.

```typescript
// recipe-brand-mentions.ts
// Daily brand-mention sweep with dedupe. Persist `seen` anywhere durable
// (a JSON file, Redis, a DB table) between runs.
// Run with: SOCIALCRAWL_KEY=sc_... npx tsx recipe-brand-mentions.ts

import { readFile, writeFile } from "node:fs/promises";

const KEY = process.env.SOCIALCRAWL_KEY;
if (!KEY) throw new Error("Set SOCIALCRAWL_KEY");

const BRAND = "socialcrawl";
const SEEN_FILE = "./seen-mentions.json";

// ── Step 1: One universal search call, sync mode ──────────────────────────
const url = new URL("https://www.socialcrawl.dev/v1/search/everywhere");
url.searchParams.set("query", BRAND);
url.searchParams.set("lookback_days", "1"); // only what's new since yesterday

const res = await fetch(url, {
  headers: { "x-api-key": KEY, accept: "application/json" },
});
const json = (await res.json()) as {
  success: boolean;
  data: {
    items: Array<{
      source: string;
      url: string;
      title: string;
      snippet: string;
      final_score: number;
      source_items: Array<{
        metadata?: { top_comments?: Array<{ text: string; score: number }> };
      }>;
    }>;
  };
};
if (!json.success) throw new Error("sweep failed");

// ── Step 2: Dedupe against previous runs by canonical post URL ────────────
const seen = new Set<string>(
  await readFile(SEEN_FILE, "utf8")
    .then((raw) => JSON.parse(raw) as string[])
    .catch(() => []),
);

const fresh = json.data.items.filter((item) => !seen.has(item.url));
for (const item of fresh) seen.add(item.url);
await writeFile(SEEN_FILE, JSON.stringify([...seen], null, 2));

// ── Step 3: Alert on what's new ────────────────────────────────────────────
console.log(`${fresh.length} new mentions of "${BRAND}" today`);
for (const item of fresh) {
  const top = item.source_items[0]?.metadata?.top_comments?.[0];
  console.log(`\n[${item.source}] ${item.title}`);
  console.log(`  ${item.url}`);
  if (top) console.log(`  top comment: "${top.text.slice(0, 140)}…"`);
  // Replace console.log with a Slack webhook / email / DB insert.
}
```

Run it on a daily cron and the `lookback_days=1` window plus the URL dedupe set guarantees each mention surfaces exactly once. Want only certain platforms? Add `url.searchParams.set("sources", "reddit,twitter-ai-search,tiktok")` — or `exclude` the noisy ones.

<Callout type="warn">
  Source names are not platform names, and a wrong one fails silently. The X source is called 

  **`twitter-ai-search`**

  , not 

  `twitter`

  . Unknown names in 

  `sources`

   / 

  `exclude`

   are filtered out with no error, so 

  `sources=reddit,twitter,tiktok`

   succeeds, quietly drops X coverage, and still charges the full flat 20 credits. Check 

  `data.sources_called`

   in the response to confirm you got the fan-out you asked for. The 

  [full source table](/docs/search/everywhere.md#sources)

   lists all 17 canonical names.
</Callout>

What you get back [#what-you-get-back]

```jsonc
// json.data.items — each mention, ranked and comment-enriched:
[
  {
    "source": "reddit",
    "title": "Anyone tried SocialCrawl for TikTok data?",
    "url": "https://reddit.com/r/webscraping/comments/...",
    "snippet": "Looking for an alternative to running my own scrapers...",
    "final_score": 0.88, // <-- RRF + rerank fused
    "source_items": [
      {
        "metadata": {
          "top_comments": [
            {
              "text": "Been using it for 3 months, the unified schema is the killer feature.",
              "score": 41,
            },
          ],
        },
      },
    ],
  },
  // ... mentions from twitter, youtube, tiktok, hackernews, ...
]
```

Credits cost [#credits-cost]

> **Cost per run:** 20 credits flat per sweep, regardless of how many platforms return mentions. A daily sweep costs 600 credits/month; hourly costs 14,400/month. Per-platform deep dives with `/v1/tiktok/search`, `/v1/reddit/search`, or `/v1/youtube/search` add 1 credit each.

Take it further [#take-it-further]

* Feed the fresh mentions into the [Sentiment analysis](/docs/recipes/sentiment-analysis.md) recipe to label each one positive / negative / neutral before alerting.
* Monitor competitors with the same loop — just change `BRAND` — or go structural with [Competitor tracking](/docs/recipes/competitor-tracking.md).
* Run this on a managed schedule with a Monitor instead of your own cron: it delivers each sweep to a signed, retried [Monitor webhook](/docs/webhooks.md) with the run result, fired alerts, and deltas.
* See [Universal social search](/platforms/search/everywhere) for the full parameter reference, and [Social listening pulse-check](/docs/recipes/social-listening-pulse-check.md) for the streaming (SSE) variant of this call.
* Platform references: [TikTok API](/platforms/tiktok), [Reddit API](/platforms/reddit), [YouTube API](/platforms/youtube). New here? [Quickstart](/docs/quickstart.md).