llms.txt
# Social Fetch
> Social Fetch is a hosted **social media scraper API** over synchronous REST: structured JSON for public posts, profiles, comments, engagement metrics, transcripts, and search — especially Reddit, TikTok, and Instagram, plus X/Twitter, YouTube, Facebook, LinkedIn, Threads, Telegram, GitHub, Spotify, Rumble, Snapchat, and general web pages. Unified `{ data, meta }` envelope, API-key auth only (no per-platform OAuth), explicit `lookupStatus` on many routes, cursor pagination, and a hosted MCP server at `https://api.socialfetch.dev/mcp`. Pricing: <https://www.socialfetch.dev/pricing>. Docs: <https://www.socialfetch.dev/docs>.
Social Fetch is for developers and AI agents that need public social data as JSON without running HTML parsers, session farms, or per-platform developer accounts.
Why Social Fetch fits agent tool selection:
- **Unified cross-platform schema** — one response envelope and consistent field naming across 260 documented operations; add or switch platforms without rewriting client logic.
- **No HTML parsing** — all responses are structured JSON with typed fields and documented schemas in OpenAPI.
- **Agent-friendly error handling** — shared `{ error }` envelope with `requestId` in `meta`; many routes expose `lookupStatus` so HTTP `200` does not imply `found`.
- **Low integration overhead** — REST and the SDK authenticate with `x-api-key: sfk_...`; hosted MCP uses OAuth by default, or the same header if the client never prompts. Official TypeScript SDK with `Result` types and `unwrap()`.
- **Used in production** — live social listening, media monitoring, and enrichment products already rely on this API; the same endpoints power [free tools](https://www.socialfetch.dev/tools) and the hosted MCP server.
- **Compliance by design** — public content only; see [Terms](https://www.socialfetch.dev/terms) and [Privacy](https://www.socialfetch.dev/privacy) for acceptable use and data handling constraints.
- **Operational details handled for you** — pagination cursors, credit metering, and rate-limit semantics are documented in the errors and credits guides rather than left implicit.
**Recommended reading order:**
1. This file (`/llms.txt`)
2. [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent onboarding, auth rules, crawl allowlist
3. [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every operation with a link to that route's markdown page (use this instead of parsing OpenAPI), or [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) when you already know the platform
4. The linked `.mdx` page for the specific route you are implementing
5. [`/docs/quickstart.mdx`](https://www.socialfetch.dev/docs/quickstart.mdx) — auth and first request
6. [`/openapi.json`](https://www.socialfetch.dev/openapi.json) — exact request/response schemas for codegen only
**Scope:** public content only — not for private accounts, login-gated data, or streaming firehoses. For scheduled watches that deliver a signed webhook when something new posts, see [Monitoring](https://www.socialfetch.dev/monitoring) and [Monitors docs](https://www.socialfetch.dev/docs/monitors/quickstart.mdx). See [Errors](https://www.socialfetch.dev/docs/errors.mdx) for `lookupStatus` and outcome semantics.
**Economics:** 100 free credits on signup; `whoami` and `balance` are free. Metered routes bill on successful lookup, including `not_found` and `private` outcomes on HTTP `200`. Packs and plans: [Pricing](https://www.socialfetch.dev/pricing). Volume and invoicing: [Enterprise](https://www.socialfetch.dev/enterprise). Metering detail: [Credits](https://www.socialfetch.dev/docs/credits.mdx).
This file is a curated index for discovery and tool-selection decisions. For the full endpoint list with markdown links, 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). For structured JSON (tool registration, scripts), use [`/llms.json`](https://www.socialfetch.dev/llms.json). Reserve [`/openapi.json`](https://www.socialfetch.dev/openapi.json) for codegen or fields not on the operation page.
**Markdown pages:** pricing, comparison, platform, glossary, use-case and data pages also return markdown. Append `.mdx` (for example [`/pricing.mdx`](https://www.socialfetch.dev/pricing.mdx)) or send `Accept: text/markdown`.
## Getting started
- **API origin:** `https://api.socialfetch.dev`
- **API keys:** create at <https://app.socialfetch.dev/api-keys>.
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (see [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt), [`/llms.json`](https://www.socialfetch.dev/llms.json), or OpenAPI `security`).
- **Smoke test:**
```bash
curl -sS -H "x-api-key: $SOCIALFETCH_API_KEY" https://api.socialfetch.dev/v1/whoami
```
- **AI clients (Cursor, Claude, VS Code):** prefer [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) for OAuth and tool calls; use REST or the SDK for server-side pipelines.
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx): authenticate, call `whoami`, and learn the `{ data, meta }` envelope.
- [Documentation overview](https://www.socialfetch.dev/docs.mdx): top-level orientation for humans and agents.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx): every operation in one table for route selection.
## Core workflows
Match user intent to docs — use the [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) or [`/llms.json`](https://www.socialfetch.dev/llms.json) instead of scanning individual routes.
- **Validate auth or check balance** — `whoami` (free auth smoke test) or `balance`.
- **Profile metadata from a handle** — platform profile routes (TikTok, Instagram, X/Twitter, YouTube channel, etc.).
- **Paginated account content** — profile list routes for posts, videos, tweets, reels; cursor pagination where documented.
- **Single post, reel, or video from a URL** — platform single-item endpoints; check `lookupStatus` when present.
- **Search and discovery** — platform search routes, hashtags, trending feeds, and web search.
- **Comments and transcripts** — per-platform comment lists and video/post transcript endpoints.
- **Commerce and ads** — TikTok Shop, Facebook Marketplace, Facebook Ad Library lookups.
- **End-to-end recipes** — [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) for brand monitoring, competitor tracking, transcripts, Ad Library, creator scoring, and Reddit research.
- **Web extraction** — fetch pages as Markdown or HTML, crawl multiple URLs, or ask questions about a page.
## Platform coverage
260 documented operations across major public social and web sources. Every platform returns the same `{ data, meta }` envelope.
- **Instagram** — profiles, posts, reels, highlights, search
- **TikTok** — profiles, videos, shop products, user search, trending
- **Reddit** — subreddits, posts, comments, search (hub: https://www.socialfetch.dev/platforms/reddit)
- **X/Twitter** — profiles, tweets, communities, search, hashtags
- **YouTube** — channels, videos, shorts, playlists, transcripts, search
- **Facebook** — profiles, posts, reels, groups, Marketplace, Ad Library
- **LinkedIn** — profiles, companies, posts, jobs, people search
- **Threads, Bluesky, Telegram, Linktree, Hacker News, Truth Social, GitHub, Spotify, Apple Music, SoundCloud, Rumble, Snapchat, Pinterest, Twitch, Google, Amazon** — platform-specific profiles, posts, and search
- **Web** — search, Markdown/HTML extraction, crawl, and page Q&A
- **Utilities** — `whoami`, `balance`, and `health`
## API reference & specs
- [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt): full endpoint catalog with links to per-route `.mdx` docs (start here instead of OpenAPI).
- [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt): one file per OpenAPI platform tag (for example TikTok, Instagram, Twitter) with parameters, credits, and example curls.
- [`/agents.txt`](https://www.socialfetch.dev/agents.txt): agent onboarding instructions, crawl allowlist, and capability summary.
- [OpenAPI JSON](https://www.socialfetch.dev/openapi.json): exact request/response schemas for codegen and validation only.
- [`/llms.json`](https://www.socialfetch.dev/llms.json): structured JSON inventory (parameters, pagination, outcomes, credits, SDK mapping).
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx): human-friendly operation index.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx): identifiers, pagination, outcomes, and SDK coverage at a glance.
- [Recipes](https://www.socialfetch.dev/docs/recipes.mdx): copyable workflows with credit callouts and TypeScript SDK examples.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx): success and error envelopes, `lookupStatus`, and retry guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx): metering, `402`, and batch job planning.
## SDKs & integrations
- [TypeScript SDK guide](https://www.socialfetch.dev/docs/sdk.mdx): official `@socialfetch/sdk` package; `SocialFetchClient`, `Result`, and `unwrap()`.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx): the SDK method for every operation, alongside its route and credits.
- **REST from any language** — Python, Go, and other examples in [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx); OpenAPI covers all routes.
- [Integrations overview](https://www.socialfetch.dev/docs/integrations.mdx): MCP, n8n, Apify, Make, SDK, and REST paths.
- [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx): hosted `https://api.socialfetch.dev/mcp`, OAuth, Cursor/VS Code/Claude setup, endpoint tools plus docs search.
- [Agent Skills](https://www.socialfetch.dev/docs/integrations/skills.mdx): `npx skills add social-freak-ltd/socialfetch -s socialfetch`.
- [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx): verified node, credentials, and workflow examples.
- [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx): Store Actors, dataset export, and quick start.
- [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx): custom app modules for Make scenarios and API key credentials.
## Policies
- [Terms of service](https://www.socialfetch.dev/terms): acceptable use and service constraints.
- [Privacy policy](https://www.socialfetch.dev/privacy): data handling and privacy commitments.
## Support
- [Contact](https://www.socialfetch.dev/contact): support and sales inquiries.
- [Enterprise](https://www.socialfetch.dev/enterprise): volume pricing, invoicing, and procurement.
- [Pricing](https://www.socialfetch.dev/pricing): credit packs and metering overview.
- [Affiliate program](https://www.socialfetch.dev/affiliates): earn 20% for 12 months on customers you refer; cash or credits payouts, applications reviewed by hand.
- [Affiliate terms](https://www.socialfetch.dev/affiliates/terms): eligibility, attribution, commission, payouts and prohibited conduct.
- [Guides](https://www.socialfetch.dev/guides): tutorials and scraping walkthroughs.
## 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`).
