The official TypeScript SDK for Social Fetch

If you are calling the Social Fetch API from Node.js or an edge worker, you can keep writing fetch wrappers. The SDK is for when you want method names that match the REST routes, typed response bodies, and one failure model you can branch on without re-reading the OpenAPI spec every week.

The package is @socialfetch/sdk on npm. Install it, pass your API key, and call the same routes you would hit over HTTP:

What the SDK gives you

SocialFetchClient exposes a namespace per platform (tiktok, instagram, twitter, reddit, linkedin, and the rest), plus web for URL extraction, auth.whoami() and billing.getBalance() for free connectivity checks, and top-level health() and ask(). Method names map to HTTP routes: client.tiktok.getProfile({ handle }) is GET /v1/tiktok/profiles/{handle}, client.instagram.getPost({ url }) is GET /v1/instagram/posts, and so on.

Expected API and runtime failures come back as { ok: false, error } instead of thrown exceptions. Successful calls return { ok: true, value } where value is the same { data, meta } envelope the REST API returns, including meta.requestId, meta.creditsCharged, and meta.version.

The SDK is not a separate product with different rules. It is the documented API with TypeScript types on top. Run it from your backend, Cloudflare Worker, or cron job. API keys belong server-side, not in browser bundles.

Result-based error handling

SDK methods return a Result type. That keeps the failure path next to the call:

Log error.requestId on failures. Branch on error.code to decide whether to retry, skip a record, or show a message upstream. The SDK normalizes API errors (unauthorized, insufficient_credits, lookup_failed) and client-side failures (network_error, parse_error) into the same shape.

Prefer exceptions? Use unwrap

Some codebases prefer try/catch. Import unwrap() and it throws SocialFetchUnwrapError when result.ok is false:

Either pattern keeps the same normalized error details. Pick the one that matches how the rest of your app handles failures.

Domain outcomes vs SDK failures

The SDK preserves the API's outcome semantics. A route can return HTTP 200 with data.lookupStatus: "not_found", "private", or "restricted". That is a completed lookup with domain data, not an SDK failure.

After result.ok is true, read result.value.data.lookupStatus (when the route provides it) before you touch profile or post fields. Log result.value.meta.requestId whenever you need to trace a call in support.

Some list routes omit lookupStatus and can return empty arrays for more than one reason. See Errors for disambiguation patterns.

Billing on completed lookups

Metered routes charge credits when we complete a lookup attempt, same as raw HTTP. That includes not_found, private, and restricted outcomes that come back as HTTP 200 with a lookupStatus in the body. Pre-send validation errors, lookup_failed, and 503 temporarily_unavailable do not bill the same way.

Reconcile your ledger against meta.creditsCharged on every response, not your request count. Per-route costs are in the API reference. Full rules: Credits.

Before you hit metered routes in a new environment, call client.auth.whoami(). It checks your API key and costs nothing.

Get started

Start with the TypeScript SDK guide for install steps, Result handling, and unwrap() details. Keep the SDK reference open for the method inventory and route mapping. Use the API reference when you need exact params and schemas.

If this is your first integration, read Quickstart for auth headers, Errors for retry rules, and Pricing to model volume.

Same envelope as curl. Fewer hand-written wrappers.