SocialCrawl

Brand mention monitoring

Run a daily brand-mention sweep across 12 social platforms with one API call, dedupe against yesterday's results, and alert on what's new — 20 credits per sweep.

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?

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, 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

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

One universal search endpoint plus a tiny dedupe layer:

  • GET /v1/search/everywhere — universal social search across 12 platforms (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.

// 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,tiktok") — or exclude the noisy ones.

What you get back

// 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

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

How to Monitor Brand Mentions Across Social Media with an API | Socialcrawl