> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). The sections below mirror the orientation block in [`/llms.txt`](https://www.socialfetch.dev/llms.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need a structured operation inventory. The catalog covers documented operations with on-site reference pages.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/api](https://www.socialfetch.dev/docs/api)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/api.mdx](https://www.socialfetch.dev/docs/api.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` 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:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/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()`.
- [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users.
- [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage.
- [`/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`).

---
# API reference (https://www.socialfetch.dev/docs/api)

These pages are generated from the same **public OpenAPI spec** the API serves. Parameters, status codes, schemas, and examples stay aligned with production.

<Callout type="info" title="Best way to navigate">
  Start from the platform or task you care about, then drill into the generated operation page for exact schemas and examples. If you are using a coding agent, the markdown version of this page lives at [`/docs/api.mdx`](/docs/api.mdx).
</Callout>

TikTok [#tiktok]

<Cards>
  <Card title="TikTok profile" description="`GET /v1/tiktok/profiles/:handle` — normalized public profile + metrics." href="/docs/api/v1/tiktok/profiles/handle/get" icon="<AtSign className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="TikTok profile videos" description="`GET /v1/tiktok/profiles/:handle/videos` — paginated videos for a profile." href="/docs/api/v1/tiktok/profiles/handle/videos/get" icon="<Video className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="TikTok video or post" description="`GET /v1/tiktok/videos/...` — normalized metadata for a single TikTok video." href="/docs/api/v1/tiktok/videos/get" icon="<ImageIcon className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>

Facebook [#facebook]

<Cards>
  <Card title="Facebook profile" description="`GET /v1/facebook/profiles` — normalized public profile or page lookup by URL." href="/docs/api/v1/facebook/profiles/get" icon="<AtSign className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>

Instagram [#instagram]

<Cards>
  <Card title="Instagram profile" description="`GET /v1/instagram/profiles/:handle` — profile, metrics, recent posts, related accounts." href="/docs/api/v1/instagram/profiles/handle/get" icon="<AtSign className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Instagram profile posts" description="`GET /v1/instagram/profiles/:handle/posts` — paginated posts for a profile." href="/docs/api/v1/instagram/profiles/handle/posts/get" icon="<List className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Instagram post or reel" description="`GET /v1/instagram/posts/...` — metadata for a single post or reel." href="/docs/api/v1/instagram/posts/get" icon="<ImageIcon className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>

Twitter [#twitter]

<Cards>
  <Card title="Twitter profile" description="`GET /v1/twitter/profiles/:handle` — normalized public profile and metrics." href="/docs/api/v1/twitter/profiles/handle/get" icon="<AtSign className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Twitter profile tweets" description="`GET /v1/twitter/profiles/:handle/tweets` — paginated tweets for a profile." href="/docs/api/v1/twitter/profiles/handle/tweets/get" icon="<List className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Twitter tweet" description="`GET /v1/twitter/tweets/...` — normalized metadata for a single tweet." href="/docs/api/v1/twitter/tweets/get" icon="<MessageSquare className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>

Utilities [#utilities]

<Cards>
  <Card title="Whoami" description="`GET /v1/whoami` — validate keys; no credits charged." href="/docs/api/v1/whoami" icon="<User className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Balance" description="`GET /v1/balance` — current credit balance; no credits charged." href="/docs/api/v1/balance" icon="<Coins className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Health check" description="`GET /health` — liveness probe, no authentication." href="/docs/api/health/get" icon="<Activity className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>

OpenAPI and machine-readable docs [#openapi-and-machine-readable-docs]

* Download the spec from &#x2A;*[`/openapi.json`](/openapi.json)**.
* Append &#x2A;*`.mdx`** to any docs page URL when you want the markdown version.
* Use [`/llms.txt`](/llms.txt) when you want a curated machine-readable map of the most important Social Fetch docs pages.
* If you are integrating from TypeScript, start with the [SDK guide](/docs/sdk).