What are API credits?
On Social Fetch, credits are the billing unit for metered lookups. Each documented route costs a fixed number of credits when we complete a lookup attempt. When spendable balance hits zero, those routes return HTTP 402 instead of doing the work.
When credits are charged
Credits are charged when we finish a lookup attempt as documented for that endpoint. That includes outcomes like private or not_found profiles returned in a 200 body via lookupStatus. Those are completed lookups, not free misses.
GET /v1/whoami and GET /v1/balance are free. Reconcile your ledger against meta.creditsCharged on each response.
Pay-as-you-go and subscriptions
Default is pay-as-you-go: buy credit packs, spend them anytime. PAYG credits do not expire. Optional subscriptions add included monthly credits for steadier volume; unused included credits do not roll over.
Exact pack sizes and plan names live on /pricing. Integrator detail is in /docs/credits.
FAQ
What happens when I run out of credits?
Metered routes return 402 insufficient_credits. Treat that as a signal to top up or pause, not as an unexpected crash.
Do failed HTTP errors still charge?
Follow each route's docs. Documented lookupStatus outcomes on 200 responses meter. Transport failures and some error classes do not. See /docs/credits and /docs/errors.
How do I check balance?
Call GET /v1/balance (free) or open billing in the app. Auto-refill options for subscribers and PAYG are described in the credits docs.
Where are per-route costs?
On each operation page under /docs/api, and on platform hubs under /platforms.