Social Fetch

Credits

Metered usage, billing signals, and how to plan integrations without surprise credit behavior

Most lookup endpoints consume credits from your account balance. When the balance runs out, those routes return 402 instead of doing the work.

How metering works

  • Credits are charged when the lookup completes successfully, as documented per endpoint. "Successful" includes outcomes like a private or not-found profile, or a restricted post — these come back in the 200 body (via data.lookupStatus), not as HTTP errors, and they still cost credits.
  • GET /v1/whoami and GET /v1/balance are free — use them for connectivity checks and balance reads without spending credits.
  • The exact cost per route lives in the API reference, on each operation's page.

Planning your integration

  • Check your balance before high-volume jobs with GET /v1/balance (or your own ledger).
  • Treat 402 as a signal, not a crash — top up, throttle, or pause until you have credits.
  • Reconcile against meta.creditsCharged so your accounting matches what actually billed.

Balance endpoint

GET /v1/balance — read your current credit balance for free.

API reference

Per-operation credit cost for every endpoint.

Errors & outcomes

Why not_found and private outcomes arrive as HTTP 200 — and still bill.

Errors

Error envelopes, request IDs, outcome handling, and common retry decisions

TypeScript SDK

Install and use the official TypeScript SDK for Social Fetch with a concrete method inventory, route mapping, unwrap guidance, and parity with documented public routes

On this page

How metering worksPlanning your integration