Brand monitoring

Watch public mentions of a brand without maintaining per-platform scrapers. Use POST /v1/ask once to learn which typed route fits a question, then call that search endpoint on a cron. Social Fetch does not push webhooks — listening is pull + your scheduler.

You'll need an API key and the TypeScript SDK. For agent prototyping, connect MCP and use nl_ask_post the same way.

Credit budget

Rough daily math: platforms × keywords × polls_per_day × credits_per_call. Example: 4 platforms × 3 terms × 24 hourly polls × ~1.5 avg credits ≈ 432 credits/day (X at 2 credits pulls the average up).

Step 1: Discover with Ask

Ask is one-shot routing, not a chat. Read data.routedOperation, then switch to the typed SDK method for every repeat call.

import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
  apiKey: process.env.SOCIALFETCH_API_KEY!,
});

const ask = await client.ask({
  query: "Search recent TikTok videos mentioning Acme coffee",
});

if (!ask.ok) {
  console.error(ask.error.code, ask.error.requestId);
  return;
}

console.log(ask.value.data.routedOperation);
console.log(ask.value.meta.creditsCharged); // nested lookup only

MCP equivalent: tool nl_ask_post with { "query": "…" }.

Step 2: Pin platform search

Once you know the routes, call them directly:

async function pollBrand(query: string) {
  const capturedAt = new Date().toISOString();

  const [tiktok, twitter, youtube, reddit] = await Promise.all([
    client.tiktok.searchVideos({ query, sortBy: "date-posted" }),
    client.twitter.search({ query, section: "latest", language: "en" }),
    client.youtube.search({ query, uploadDate: "this_week", sortBy: "relevance" }),
    client.reddit.search({ query, sortBy: "new", timeframe: "week" }),
  ]);

  return {
    capturedAt,
    batches: [
      { platform: "tiktok", result: tiktok },
      { platform: "twitter", result: twitter },
      { platform: "youtube", result: youtube },
      { platform: "reddit", result: reddit },
    ],
  };
}

Branch on result.ok first. On success, store meta.requestId and meta.creditsCharged with each snapshot. Paginate with data.page.nextCursor / hasMore when you need more than one page.

Hashtag campaigns: TikTok hashtags, YouTube hashtags, Twitter hashtags.

Step 3: Dedupe in your warehouse

Social Fetch returns point-in-time JSON. Upsert on (platform, postId), compare today's net-new IDs to a baseline, and alert on velocity — not on items.length from a single poll.

Longer pipeline (cron, spike detection, Slack): Build a social listening dashboard.

Related

• Ask · Credits · MCP · SDK
• Platforms: TikTok · Twitter · YouTube · Reddit