What are API credits?
Credits are Social Fetch's billing unit for metered lookups: each documented route has a fixed cost, deducted when a lookup attempt completes. New accounts get 100 free credits, no card required; at zero balance, metered routes return HTTP 402.
What a credit actually buys
A credit is metered usage, not a pre-allocated budget per call. Each endpoint has a fixed cost (most typed lookups are 1 credit; lists and transcripts can cost more). Every response reports the charge in meta.creditsCharged.
One balance and one API key cover every platform — TikTok through web extraction — with no per-platform sub-balance.
A concrete example
A TikTok profile lookup with a found result: meta.creditsCharged: 1. A not_found on the same route: still HTTP 200, still creditsCharged: 1 — the attempt completed.
POST /v1/ask routes for 0 credits; the nested lookup bills exactly as a direct typed call would.
When credits are charged, and when they're not
Charged when a lookup completes as documented — including private or not_found on HTTP 200 via data.lookupStatus.
Not charged on lookup_failed or 503 temporarily_unavailable. GET /v1/whoami and GET /v1/balance are always free.
Packs, plans, and how the price scales
Default is pay-as-you-go: Starter $14/1,000, Growth $47/25,000 (~$1.88/1k), Scale $379/230,000 (~$1.65/1k). PAYG credits never expire.
No subscription required. Optional monthly plans exist for predictable spend. Details on /pricing and /docs/credits.
How this compares to subscription-tier billing
Many APIs bundle monthly quotas that reset or charge overage. Credits decouple spend from a billing cycle — unused PAYG credits don't expire, and scaling up is buying a pack, not migrating plans.
Common mistakes and what credits are not
Assuming not_found or private was free because "nothing returned." Check data.lookupStatus — 200 with not_found is billed. Retrying won't change the outcome.
Credits aren't a rate limit — low balance doesn't throttle RPS; see /glossary/rate-limits. Reconcile via meta.creditsCharged or GET /v1/balance.
FAQ
How do API credits work?
Fixed cost per route, deducted on completed lookups, reported in meta.creditsCharged. Zero balance → HTTP 402 on metered routes.
Do unused credits expire?
PAYG packs never expire. Optional subscription included credits don't roll over — but PAYG balance has no expiry.
What counts as a completed lookup for billing?
Any attempt that finishes as documented, including private or not_found on HTTP 200.
Does a not_found result cost credits?
Yes. lookup_failed and 503 temporarily_unavailable don't charge.
What happens when I run out of credits?
HTTP 402 insufficient_credits on metered routes. whoami and balance stay free.
Do I need a subscription to use Social Fetch?
No. PAYG packs are the default; subscriptions are optional.
How much do API credits cost?
Starter $14/1k, Growth $47/25k, Scale $379/230k. 100 free credits on signup. See /pricing.
Does routing a request through /v1/ask cost extra credits?
No. Routing is 0 credits; the nested lookup bills normally.