> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/use-cases/social-media-monitoring-api>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/use-cases/social-media-monitoring-api.mdx>

---

# Social media monitoring API

Scheduled keyword and hashtag search across 57 platforms. Same data + meta envelope every poll; credits deduct on completed lookups.

Broad keyword listening means scheduled search, snapshot storage, diffing, then alerts — not a push stream. DIY scrapers break on schema drift; SaaS seats bill while crisis terms sit quiet.

For a single account or hashtag, use Monitors (signed webhook, no cron). This page covers multi-term watches: brand mentions, competitor share-of-voice, crisis spikes.

Social Fetch search endpoints share lookupStatus, pagination cursors, and meta.requestId. You own dedupe, filters, and alert thresholds.

## Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| GET | `/v1/twitter/search` | Crisis and brand mention polling on X. Use section=latest for fresh posts, language for locale-scoped watches, startDate/endDate to bound a window. One credit per successful request. |
| GET | `/v1/tiktok/search` | Keyword search with datePosted (today, this-week, this-month) and optional region code for localized result sets. |
| GET | `/v1/tiktok/search/hashtags` | Campaign and branded hashtag tracking with cursor pagination — typical for launch wrap-ups and UGC volume charts. |
| GET | `/v1/youtube/search/hashtags` | Discover YouTube videos tagged with a campaign hashtag for cross-platform share-of-voice next to TikTok. |
| GET | `/v1/reddit/search` | Catch brand and competitor mentions in subreddit discussions — often the earliest honest signal before a story hits mainstream feeds. |
| GET | `/v1/tiktok/videos/comments` | Pull comment threads on posts that crossed your velocity threshold — hand text to keyword rules or a sentiment model after the search job flags them. |

## Workflow

1. **Define watch lists and alert rules.** Group keywords by job: brand exact match, competitor aliases, crisis misspellings. Set baseline volume per term and spike multipliers (e.g. 3× the seven-day median) before writing cron schedules — alerts should fire on diffs, not raw result counts.
2. **Poll on cadence, not a firehose.** There is no platform push stream here — you GET on a schedule (cron, QStash, Temporal). Run section=latest on X every few minutes for incident watches; poll hashtags hourly for campaign dashboards. Credits deduct per completed lookup, so match frequency to risk.
3. **Filter noise at the API.** Narrow before you store: language on X, datePosted on TikTok, minLikes/minRetweets to drop low-engagement hits, region on TikTok hashtag search for proxy locale. Post-filter in SQL on author handle or URL domain if you maintain blocklists.
4. **Dedupe and snapshot.** Upsert rows keyed by platform + post ID. Append meta.requestId and capturedAt on every poll so you can replay a spike window. Re-running the same cursor chain twice will bill twice — treat cursors as single-use pagination tokens.
5. **Diff, then alert.** Compare today's IDs against the last snapshot. Route only net-new high-velocity posts to Slack, email, or your on-call tool. Empty arrays still cost a credit when lookupStatus is success — budget for quiet terms.
6. **Enrich for sentiment when it matters.** Search finds the post; comments endpoints pull audience reaction on the items that breached your threshold. Pair with your classifier or the comments-for-sentiment workflow — captions alone miss most brand damage in threads.

## Example: crisis watch on X (latest posts, English only)

```bash
curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  -G "https://api.socialfetch.dev/v1/twitter/search" \
  --data-urlencode "query="yourbrand" OR yourbrand" \
  --data-urlencode "section=latest" \
  --data-urlencode "language=en"
```

## Why monitoring teams poll with Social Fetch

- One API key and envelope from TikTok search through Reddit comments — your dedupe table does not fork per network.
- No published rate cap beyond credit balance; burst parallel polls during an incident without negotiating a tier upgrade.
- Prepaid credits with no expiry — run listening three times a month or every five minutes during a launch from the same balance.
- lookup_failed and 503 responses do not charge; successful empty results do — predictable math for cron budgeting.
- Platform filter params (section, language, datePosted, region) cut warehouse noise before you pay for storage and LLM scoring.
- Schema stays stable when platform HTML changes — alert code keeps reading data.items and meta.creditsCharged.
