Choose the right API endpoint
Pick the Social Fetch route for profiles, paginated feeds, single-item lookups, auth checks, 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
whoamiwhen you want the cheapest auth smoke test. - Use
healthwhen 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 |
GET /v1/twitter/profiles/{handle} | client.twitter.getProfile({ handle }) | handle | |
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 |
GET /v1/twitter/profiles/{handle}/tweets | client.twitter.getProfileTweets({ handle, limit?, cursor?, includeReplies?, includePinned? }) | Cursor via data.page.nextCursor. Defaults to 40 tweets per page. Use GET /v1/twitter/profiles/{handle} first if you need to distinguish private vs not-found before interpreting an empty list. | |
GET /v1/instagram/profiles/{handle}/posts | client.instagram.getProfilePosts({ handle, cursor? }) | Cursor-based. Use data.lookupStatus for private/restricted vs not found vs a public empty feed. |
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 |
GET /v1/twitter/tweets | client.twitter.getTweet({ url, trim? }) | Tweet permalink or identifier in url | |
GET /v1/instagram/posts | client.instagram.getPost({ url, ... }) | URL. Check data.lookupStatus for found, not_found, or restricted (age-gated or otherwise not publicly scrapable). |
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 restricted from not_found on a post or reel URL?"
On GET /v1/instagram/posts, both outcomes are HTTP 200 with empty post / media fields. Use data.lookupStatus: not_found when the target does not exist or cannot be resolved; restricted when the post is not available under public scraping (for example age-gated content). Do not retry restricted as a transient failure. 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.