> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration. ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** ## API base URL and authentication - **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev` - **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route). - **OpenAPI JSON:** ## Recommended docs entrypoints (this site) - [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown). - [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope. - [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`. - [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages. - [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples. - [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths. - [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install. - [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 910 endpoint tools, plus docs_search/docs_read for implementation help. - [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples. - [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start. - [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog. - [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI). - [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls). - [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist. - [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping. - [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages. - [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance. - [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs. - Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract. ## Markdown docs convention - Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`). - Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`). - Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`). --- # Listening alerts and exports (https://www.socialfetch.dev/docs/tools/listening/alerts-and-exports) {/* Rules follow packages/saved-queries/src (service.ts spikes, thresholds.ts, briefings.ts) and saved-queries-shared.ts (export limit). Update them here if they change. */} Alerts, briefings, webhooks and downloads are all free. Set them when you save a topic, under **More** in the **Keep listening** dialog, or later in the topic's **Settings** (the webhook is set when you save). There are no emails: alerts show on the topic's page and on the Listening page, and go to its webhook if it has one. ## Volume alerts **Alert me when it finds N or more posts in an hour (or a day).** When a run takes the topic over that number of new posts in the last hour or day, the topic shows **Volume alert: N posts found in the last hour (alert at M)**, and its webhook gets a `saved_query.threshold` event with five of the posts. * It alerts at most once a window. * An hourly alert needs a topic that runs at least hourly, and a daily one a topic that runs at least daily. * A run catching up after a long gap doesn't alert. * With insights on, only posts about the topic count. ## Spikes Spikes need no setting: a topic spikes when a day brings far more posts than usual. See [Spikes](/docs/tools/listening/read-your-results#spikes). Its webhook gets a `saved_query.spike` event with five of the posts. ## Briefings A **briefing** sums up a period: how many posts, the change on the period before, the stories (reposts and copies counted once), each platform's posts, the loudest voices and the most engaged posts, and, with insights, how many need a reply and the riskiest posts. Nothing in it is written by AI: every figure comes from the posts kept. * **Daily, 08:00 UTC** covers the day before; **Weekly, Monday 08:00 UTC** covers Monday to Sunday. * It shows on the topic's page and goes to its webhook as `saved_query.briefing`. * A topic gets one only for a period in which it was active and ran. ## Webhooks A topic with a webhook endpoint sends each run's new posts to it as a `saved_query.matches` event (up to 25 posts, with a link to see the rest), as well as its spikes, volume alerts and briefings. Each post includes its sentiment and insights when those are on. Create endpoints under [Monitors → Webhooks](https://app.socialfetch.dev/monitors/webhooks), then choose one in the **Keep listening** dialog. See [Webhooks](/docs/monitors/webhooks) for signatures and retries, and the [saved queries recipe](/docs/recipes/saved-queries) for each event's payload. ## Download On a topic's page, **Download** gives its posts as: * **CSV**: the posts it keeps, newest first, for a spreadsheet. * **JSON**: every field, as the API gives it. A download holds the newest 5,000 posts. It includes your corrections to sentiment and relevance. ## The API Topics are **saved queries** in the API, and the app and the API share them: a topic you save in the app is in the API, and the other way round. The [saved queries recipe](/docs/recipes/saved-queries) covers saving one, reading its posts (with the same filters), stats, and every webhook event. To search once without saving, use [Search with a query](/docs/api/v1/query/search/post). - [Costs and limits](/docs/tools/listening/costs-and-limits) — Everything that uses credits. - [Troubleshooting](/docs/tools/listening/troubleshooting) — The messages Listening shows, and what to do about them.