> **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/sdk-reference](https://www.socialfetch.dev/docs/sdk-reference) - **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/sdk-reference.mdx](https://www.socialfetch.dev/docs/sdk-reference.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`). --- # SDK reference (https://www.socialfetch.dev/docs/sdk-reference) SDK inventory [#sdk-inventory] The current `SocialFetchClient` exposes five resource namespaces plus one top-level utility: | Surface | Methods | Wrapped routes | | ----------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *(client)* | `health()` | `GET /health` | | `auth` | `whoami()` | `GET /v1/whoami` | | `billing` | `getBalance()` | `GET /v1/balance` | | `tiktok` | `getProfile()`, `getProfileLive()`, `getProfileVideos()`, `getVideo()`, `getVideoComments()`, `getVideoTranscript()` | `GET /v1/tiktok/profiles/{handle}`, `GET /v1/tiktok/profiles/{handle}/live`, `GET /v1/tiktok/profiles/{handle}/videos`, `GET /v1/tiktok/videos`, `GET /v1/tiktok/videos/comments`, `GET /v1/tiktok/videos/transcript` | | `twitter` | `getProfile()`, `getProfileTweets()`, `getTweet()` | `GET /v1/twitter/profiles/{handle}`, `GET /v1/twitter/profiles/{handle}/tweets`, `GET /v1/twitter/tweets` | | `instagram` | `getProfile()`, `getProfilePosts()`, `getPost()` | `GET /v1/instagram/profiles/{handle}`, `GET /v1/instagram/profiles/{handle}/posts`, `GET /v1/instagram/posts` | Method-by-method reference [#method-by-method-reference] ```ts client.health() client.auth.whoami() client.billing.getBalance() client.tiktok.getProfile({ handle }) client.tiktok.getProfileLive({ handle }) client.tiktok.getProfileVideos({ handle, sortBy?, cursor?, userId?, region?, trim? }) client.tiktok.getVideo({ url, region?, trim?, downloadMedia? }) client.tiktok.getVideoComments({ url, cursor?, trim? }) client.tiktok.getVideoTranscript({ url, language?, useAiFallback? }) client.twitter.getProfile({ handle }) client.twitter.getProfileTweets({ handle, trim? }) client.twitter.getTweet({ url, trim? }) client.instagram.getProfile({ handle }) client.instagram.getProfilePosts({ handle, cursor? }) client.instagram.getPost({ url, region?, trim?, downloadMedia? }) ``` Route mapping [#route-mapping] | SDK method | HTTP route | Main identifiers / params | | --------------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------- | | `client.health()` | `GET /health` | none | | `client.auth.whoami()` | `GET /v1/whoami` | none | | `client.billing.getBalance()` | `GET /v1/balance` | none | | `client.tiktok.getProfile({ handle })` | `GET /v1/tiktok/profiles/{handle}` | `handle` | | `client.tiktok.getProfileLive({ handle })` | `GET /v1/tiktok/profiles/{handle}/live` | `handle` | | `client.tiktok.getProfileVideos({ handle, sortBy?, cursor?, userId?, region?, trim? })` | `GET /v1/tiktok/profiles/{handle}/videos` | `handle`, `sortBy`, `cursor`, `userId`, `region`, `trim` | | `client.tiktok.getVideo({ url, region?, trim?, downloadMedia? })` | `GET /v1/tiktok/videos` | `url`, `region`, `trim`, `downloadMedia` | | `client.tiktok.getVideoComments({ url, cursor?, trim? })` | `GET /v1/tiktok/videos/comments` | `url`, `cursor`, `trim` | | `client.tiktok.getVideoTranscript({ url, language?, useAiFallback? })` | `GET /v1/tiktok/videos/transcript` | `url`, `language`, `useAiFallback` | | `client.twitter.getProfile({ handle })` | `GET /v1/twitter/profiles/{handle}` | `handle` | | `client.twitter.getProfileTweets({ handle, trim? })` | `GET /v1/twitter/profiles/{handle}/tweets` | `handle`, `trim` | | `client.twitter.getTweet({ url, trim? })` | `GET /v1/twitter/tweets` | `url`, `trim` | | `client.instagram.getProfile({ handle })` | `GET /v1/instagram/profiles/{handle}` | `handle` | | `client.instagram.getProfilePosts({ handle, cursor? })` | `GET /v1/instagram/profiles/{handle}/posts` | `handle`, `cursor` | | `client.instagram.getPost({ url, region?, trim?, downloadMedia? })` | `GET /v1/instagram/posts` | `url`, `region`, `trim`, `downloadMedia` |