---
name: socialfetch
description: >-
  Onboard coding agents to Social Fetch — a public social data / social media
  scraper API (REST) for Reddit, TikTok, Instagram, X/Twitter, YouTube, and
  more. Read llms.txt / agents.txt / llms-endpoints.txt / llms-{platform}.txt,
  connect hosted MCP (OAuth), call POST /v1/ask, create an API key for REST/SDK,
  and never invent endpoints. Use when the user mentions Social Fetch,
  socialfetch.dev, social data API, MCP social tools, Reddit/TikTok/Instagram
  scrapers via API, or agent workflows that fetch public profiles, posts,
  transcripts, or metrics.
---

# Social Fetch

Social Fetch is a versioned public REST API (`https://api.socialfetch.dev`) for normalized **public** social data — profiles, posts, comments, transcripts, engagement, search. Think of it as a hosted social media scraper API: you call documented HTTP routes; Social Fetch maintains the live fetch path. One `sfk_…` API key (or MCP OAuth). Responses use a `{ data, meta }` envelope.

**Platforms (non-exhaustive):** Reddit, TikTok, Instagram, X/Twitter, YouTube, Facebook, LinkedIn, Threads, Telegram, GitHub, Spotify, Rumble, plus general web extraction. Platform hubs: https://www.socialfetch.dev/platforms — Reddit: https://www.socialfetch.dev/platforms/reddit.

**Docs / pricing:** https://www.socialfetch.dev/docs · https://www.socialfetch.dev/pricing · credits metering: https://www.socialfetch.dev/docs/credits.mdx

This skill teaches agents how to integrate Social Fetch correctly. Prefer live docs and catalogs over training data. **Never invent paths, operation IDs, or field names.**

## Hard rules

1. **Do not invent endpoints.** Only use operations listed in `/llms-endpoints.txt`, `/llms-{platform}.txt`, `/llms.json`, OpenAPI, or MCP tool schemas. If a route is not listed, it does not exist for you.
2. **Orient before coding.** Read `https://www.socialfetch.dev/llms.txt` and `https://www.socialfetch.dev/agents.txt` first, then look up the specific route.
3. **HTTP 200 is not "found".** Many lookups return `data.lookupStatus` (`found`, `not_found`, `private`, …) with HTTP 200. Treat that as data, not a transport failure. Do not retry `not_found` hoping for a different answer — it is billed.
4. **Log `meta.requestId`.** Quote it in support requests (`support@socialfetch.dev`).
5. **Keep API keys server-side.** Never put `sfk_…` in browser bundles, mobile apps, or public repos. MCP uses OAuth; do not paste a dashboard key into `mcp.json`.

## Recommended reading order

Fetch these (curl, browser tool, or MCP `docs_read`) in order:

1. `https://www.socialfetch.dev/llms.txt` — orientation, workflow, economics
2. `https://www.socialfetch.dev/agents.txt` — auth rules, pagination, crawl allowlist
3. `https://www.socialfetch.dev/llms-endpoints.txt` — every operation with a link to that route's markdown page (prefer this over parsing OpenAPI for discovery), or `https://www.socialfetch.dev/llms-{platform}.txt` when you already know the platform (example: `/llms-tiktok.txt`)
4. The linked `.mdx` page for the route you are implementing (append `.mdx` to docs URLs, or use MCP `docs_read`)
5. `https://www.socialfetch.dev/docs/quickstart.mdx` — auth and first request
6. `https://www.socialfetch.dev/openapi.json` — only for codegen / exact schemas

Also useful:

- `https://www.socialfetch.dev/llms.json` — structured operation inventory for tool registration
- `https://www.socialfetch.dev/docs/errors.mdx` — envelopes, `lookupStatus`, retries
- `https://www.socialfetch.dev/docs/credits.mdx` — what bills and what does not
- `https://www.socialfetch.dev/pricing` — credit packs and plans
- `https://www.socialfetch.dev/docs/integrations/mcp.mdx` — MCP install and OAuth
- `https://www.socialfetch.dev/docs/integrations/skills.mdx` — this skill's install docs
- `https://www.socialfetch.dev/platforms` — per-platform hubs (Reddit, TikTok, Instagram, …)

Docs pages are available as markdown (same path with `.mdx`, or `Accept: text/markdown` where supported).

## Choose a path: MCP vs REST

| Goal | Use |
| --- | --- |
| Prototype in Cursor / Claude / VS Code | Hosted MCP + OAuth |
| Production server code, CI, backends | REST or `@socialfetch/sdk` + `x-api-key` |
| Explore which route fits a question | `POST /v1/ask` or MCP `nl_ask_post` |
| Ship a stable workflow | Pin the typed route / MCP tool from `data.routedOperation` |

Details: [references/mcp.md](references/mcp.md), [references/rest.md](references/rest.md).

## Hosted MCP (OAuth)

Server URL: `https://api.socialfetch.dev/mcp`

Add that URL to the client's MCP config, restart, and finish the browser OAuth flow. Credits charge to the signed-in account. Endpoint tools bill like REST; `docs_search` and `docs_read` are free.

Cursor example (project or `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "socialfetch": {
      "url": "https://api.socialfetch.dev/mcp"
    }
  }
}
```

Claude Code:

```bash
claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp
```

Then `/mcp` → authenticate Social Fetch.

**Workflow when MCP is connected:**

1. Prefer the most specific typed tool once you know platform + resource (e.g. `tiktok_profile_get`).
2. If unsure: `docs_search` → `docs_read`, or one-shot `nl_ask_post`.
3. After profile lookups, read `lookupStatus` before assuming the account was found.
4. After metered calls, read top-level `meta.creditsCharged` and `meta.requestId`.
5. Call `billing_balance_get` before large batches.

Do not paste an API key into MCP config.

## POST /v1/ask (natural-language routing)

Use when you do not yet know which typed endpoint to call.

- **REST:** `POST https://api.socialfetch.dev/v1/ask` with JSON `{ "query": "…" }` and `x-api-key`
- **MCP:** tool `nl_ask_post` with the same idea

Routing costs **0 credits**. The nested lookup bills normally. Read `data.routedOperation` (or equivalent) and switch to that typed route/tool for repeat calls.

Requires an API key (REST) or OAuth (MCP). Not available as anonymous x402-only.

## Get an API key (REST / SDK)

1. Sign up / sign in at https://app.socialfetch.dev
2. Create a key at https://app.socialfetch.dev/api-keys (`sfk_…` prefix)
3. Send `x-api-key: sfk_…` on `/v1/**` requests
4. Smoke-test with `GET /v1/whoami` (free), then a real lookup

New accounts get free starter credits; see Credits docs for pack vs subscription rules.

TypeScript production path: `@socialfetch/sdk` — same routes as REST.

## Credits (agent-relevant)

- Metered lookups bill on completed lookup attempts, including `not_found` / `private` on HTTP 200.
- `lookup_failed` and `503 temporarily_unavailable` are not charged — retry with backoff.
- `whoami`, `balance`, and docs MCP tools are free.
- No published RPS cap on paid metered routes; practical limit is credit balance. Stay under ~500 concurrent requests for reliability.
- Pre-send validation errors (bad params) cost nothing.

## Response envelope (always)

Success shape:

```json
{
  "data": { "lookupStatus": "found" },
  "meta": {
    "requestId": "req_…",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

Failure shape uses `{ error }` with a typed `code` plus `meta.requestId`. Parse codes; do not string-match HTML.

## Scope limits

Public content only. Not for private accounts, login-gated data, webhooks, or streaming delivery. Social Fetch does not host team/workspace accounts today — each signup is one billing user.

## When stuck

1. Re-fetch `/llms.txt` and the specific route page — do not guess.
2. MCP: `docs_search` then `docs_read`.
3. Check [Errors](https://www.socialfetch.dev/docs/errors.mdx) for `lookupStatus` vs HTTP status.
4. Include `meta.requestId` when asking the user to contact support.