Choose the right endpoint

Pick the correct Social Fetch route for auth, health, profiles, paginated content, single-item lookups, and smoke tests

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

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

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

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

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
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

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

"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?"

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?"

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`?"

Do not rely on HTTP status alone. If the route exposes data.lookupStatus, inspect it on HTTP 200. See Errors.

"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.

"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

Call whoami.
Choose the route family from the tables above.
Check the Capability matrix for identifiers, pagination, outcome semantics, and SDK coverage.
Open the exact operation page in the API reference.

Choose the right endpoint

On this page