Credits

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

Some endpoints consume credits from your account balance. The API may return 402 when balance is insufficient.

Check `meta.creditsCharged`

Each successful metered response includes how many credits were billed for that call — use it for client-side accounting and alerts.

How metering works

Metered routes charge credits when the lookup attempt completes successfully, as documented per endpoint. That can include cases where the social profile is private or not found — those outcomes are returned in the 200 response body (for example data.lookupStatus on TikTok profile lookup), not as HTTP errors.
The whoami endpoint is intended for connectivity checks and does not charge credits.
Use GET /v1/balance to read your current credit balance over the public API; it does not charge credits.
Response metadata includes creditsCharged so you can confirm what was billed for that request.

Preflight your balance before high-volume jobs (for example with GET /v1/balance or your own ledger checks).
Treat 402 as a signal to top up or reduce concurrency.
See the API reference for credit amounts and endpoint identifiers (for example TikTok profile lookup).

Full list of error codes including billing failures.

Per-operation credit and pricing hints from the spec.

Outcome semantics live inside the Errors guide, including `not_found` and `private` in HTTP `200`.