> **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/choose-endpoint](https://www.socialfetch.dev/docs/choose-endpoint)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/choose-endpoint.mdx](https://www.socialfetch.dev/docs/choose-endpoint.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`).

---
# Choose the right endpoint (https://www.socialfetch.dev/docs/choose-endpoint)

Use this page when you know what outcome you want, but you are not yet sure which route or SDK method to call.

Decision rules [#decision-rules]

* Use **`whoami`** when you want the cheapest auth smoke test.
* Use **`health`** when you only care whether the service is up.
* Use **profile endpoints** for account metadata.
* Use **profile list endpoints** for paginated content from an account.
* Use **single-item endpoints** when you already have a post, reel, video, or tweet URL.
* Use **raw HTTP** when you need a documented route that the SDK does not wrap, or when you are outside TypeScript.

Utilities [#utilities]

| Goal                        | Route             | SDK                           | Why                                                              |
| --------------------------- | ----------------- | ----------------------------- | ---------------------------------------------------------------- |
| Validate auth               | `GET /v1/whoami`  | `client.auth.whoami()`        | Checks key validity without consuming credits.                   |
| Check balance               | `GET /v1/balance` | `client.billing.getBalance()` | Use before high-volume metered jobs.                             |
| Check service liveness only | `GET /health`     | `client.health()`             | Use this for liveness only. Use `whoami` for an auth smoke test. |

Profile metadata [#profile-metadata]

Use these when the input is a handle and the output is account-level information.

| Platform  | Route                                 | SDK                                       | Input    |
| --------- | ------------------------------------- | ----------------------------------------- | -------- |
| TikTok    | `GET /v1/tiktok/profiles/{handle}`    | `client.tiktok.getProfile({ handle })`    | `handle` |
| Twitter   | `GET /v1/twitter/profiles/{handle}`   | `client.twitter.getProfile({ handle })`   | `handle` |
| Instagram | `GET /v1/instagram/profiles/{handle}` | `client.instagram.getProfile({ handle })` | `handle` |

Paginated account content [#paginated-account-content]

Use these when you want posts, videos, or tweets for a profile instead of the profile itself.

| Platform  | Route                                       | SDK                                                     | Pagination                                                      |                                       |
| --------- | ------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------- |
| TikTok    | `GET /v1/tiktok/profiles/{handle}/videos`   | `client.tiktok.getProfileVideos({ handle, ... })`       | Cursor-based. Optional \`sortBy=latest                          | popular\`. Empty lists are ambiguous. |
| Twitter   | `GET /v1/twitter/profiles/{handle}/tweets`  | `client.twitter.getProfileTweets({ handle, trim? })`    | No cursor. Up to \~100 popular public posts, not chronological. |                                       |
| Instagram | `GET /v1/instagram/profiles/{handle}/posts` | `client.instagram.getProfilePosts({ handle, cursor? })` | Cursor-based. Empty first pages are ambiguous.                  |                                       |

Single-item lookups [#single-item-lookups]

Use these when you already have a canonical content URL and want one normalized object back.

| Platform  | Route                     | SDK                                       | Identifier                             |
| --------- | ------------------------- | ----------------------------------------- | -------------------------------------- |
| TikTok    | `GET /v1/tiktok/videos`   | `client.tiktok.getVideo({ url, ... })`    | URL                                    |
| Twitter   | `GET /v1/twitter/tweets`  | `client.twitter.getTweet({ url, trim? })` | Tweet permalink or identifier in `url` |
| Instagram | `GET /v1/instagram/posts` | `client.instagram.getPost({ url, ... })`  | URL                                    |

Common questions [#common-questions]

"Should I start with `health` or `whoami`?" [#should-i-start-with-health-or-whoami]

Start with `whoami` if the real question is "can this integration authenticate and read my key correctly?" Start with `health` only if you want a generic liveness probe.

"I have a profile handle. Which route do I use?" [#i-have-a-profile-handle-which-route-do-i-use]

Use the platform profile route when you want account metadata. Use the platform profile list route when you want posts, videos, or tweets from that account.

"I have a post URL. Which route do I use?" [#i-have-a-post-url-which-route-do-i-use]

Use the platform single-item endpoint. Those routes are the best fit when your input is a content URL rather than a profile handle.

"How do I tell `private` from `not_found`?" [#how-do-i-tell-private-from-not_found]

Do not rely on HTTP status alone. If the route exposes `data.lookupStatus`, inspect it on HTTP `200`. See [Errors](/docs/errors).

"How do I tell `private` from `not_found` from an empty list?" [#how-do-i-tell-private-from-not_found-from-an-empty-list]

Some list routes do not expose `lookupStatus`. If you need account-level `private` / `not_found`, call the profile route first. See [Errors](/docs/errors).

"When should I prefer the SDK?" [#when-should-i-prefer-the-sdk]

Prefer the SDK for TypeScript when the route is wrapped and you want typed `Result` handling. Prefer raw HTTP or OpenAPI when:

* you are integrating from another language
* you need to inspect the exact on-the-wire schema

Good default workflow [#good-default-workflow]

1. Call `whoami`.
2. Choose the route family from the tables above.
3. Check the [Capability matrix](/docs/capability-matrix) for identifiers, pagination, outcome semantics, and SDK coverage.
4. Open the exact operation page in the [API reference](/docs/api).