Credits

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

Social Fetch is pay-as-you-go by default — buy credit packs once and spend them whenever. PAYG credits never expire. Optional subscription plans add included credits each month for steadier volume. Plan names, pack sizes, and prices are on the Pricing page.

How metering works

• Credits are charged when we complete a lookup attempt, as documented per endpoint. That 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.
• Cache hits still charge. Some endpoints may return meta.cached: true (and an HTTP Age header) when the response comes from our short-lived completed-result cache. That avoids repeating upstream work; it is not a free or discounted credit path — meta.creditsCharged remains the full endpoint price.
• 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.

Pay-as-you-go and subscriptions

Non-subscribers spend PAYG balance only. When it is empty, metered routes return 402 insufficient_credits.

With an active subscription, usage draws credits in this order:

1. Included subscription credits for the current monthly period
2. Pay-as-you-go balance (pack purchases, free signup credits, prior refill packs)
3. Prepaid tier refill packs — auto-purchased when spendable balance drops below your refill threshold (not metered usage)

Included credits reset at the start of each monthly period — even on annual base plans, the credit clock is monthly. Unused included credits do not roll over. Your PAYG balance (pack purchases and refill-pack credits) is separate and never expires. Canceling a subscription never forfeits PAYG or refill credits.

You can buy credit packs while subscribed. PAYG balance acts as a buffer before auto-refill kicks in.

Auto-refill

Subscribers with auto-refill enabled (on by default at subscribe checkout) keep serving when included credits run out: usage continues through PAYG balance, then prepaid refill packs charge your saved card off-session. Refill credits land in your PAYG bucket and do not expire.

Auto-refill triggers when your spendable balance drops to 100 credits or below (the default threshold). You can raise the trigger in billing. You can optionally set a per-period auto-refill spend cap — when reached, refill charges stop and metered routes return 402 until the next period or you raise the cap.

Toggle auto-refill off in billing if you prefer a hard stop once included + PAYG balance are exhausted.

Subscribers can use their tier refill pack (default) or any credit top-up pack chosen in billing settings. For pay-as-you-go accounts, auto top-up is on by default after your first credit pack purchase — we charge the same pack size you bought when your balance drops to 100 credits or below (configurable in billing). Toggle it off anytime if you prefer a hard stop at zero.

Grace buffer when a refill charge fails

If an auto-refill charge fails (card declined, insufficient funds), we grant a one-time grace buffer so production apps keep running while you fix payment. Grace requires auto-refill enabled with a saved payment method, and applies only to paying accounts (you have purchased credits or subscribed). Free signup credits alone do not qualify.

Grace credits are granted once per unpaid episode. When your next successful charge succeeds (auto-refill or a credit pack purchase), the grace amount is recouped before the remainder stays in your balance. If grace is exhausted while payment still fails, requests return 402 and billing shows an update payment method banner.

This is separate from base subscription renewal failure — if base renewal payment fails at period reset, included credits for that month are skipped until the invoice pays. You keep any remaining PAYG/refill balance. Update your card in the Stripe billing portal to restore full service.

Canceling or changing plans

• Cancel from billing — effective at period end. Included credits remain until the period closes; then you revert to pay-as-you-go only.
• Upgrade takes effect immediately with a prorated charge and matching included-credit top-up.
• Downgrade schedules for period end.

Payment methods and invoices are managed through the Stripe billing portal.

Balance polling

GET /v1/balance is free. Poll it before large jobs or on a schedule.

• data.balance — spendable credits you can use right now (aligned with when metered routes return 402). During a grace episode, pre-granted grace is excluded from balance until included and regular PAYG credits are exhausted; after that, balance counts down grace runway.
• data.billingAlert — billing health for alerting: none, payment_action_required, or suspended. Check this even when balance still looks healthy — for example, auto-refill failed but the grace buffer has credits left.

Other fields (payg, paygSpendable, graceDebtCredits, refillState) break down the same state; see the Balance API reference for field descriptions.

Recommended alert (low credits or payment needs attention):

const { data } = await client.billing.getBalance();
const MIN_CREDITS = 1_000;

if (data.billingAlert !== "none" || data.balance < MIN_CREDITS) {
  notifyOps(); // fix payment in the dashboard and/or buy a pack
}

Example during grace — payment failed, spending the grace buffer (balance is runway; billingAlert is the warning):

{
  "data": {
    "balance": 1998,
    "billingAlert": "payment_action_required",
    "paygSpendable": 0,
    "refillState": "grace",
    "graceDebtCredits": 2000
  }
}

Throughput and concurrency

Paid metered /v1/* routes have no request quotas — credits are the only limit. There is no enforced requests-per-second cap on paid lookups. Run parallel requests as your product needs; for best performance and reliability, stay below ~500 concurrent requests.

Under load, requests may be queued. Under extreme concurrency, the API can return 503 temporarily_unavailable with an accurate Retry-After header. That means we are busy — not that you hit a customer rate limit (we do not use 429 for paid metered saturation). These responses are not charged on metered lookup routes. Honor Retry-After (or use gradual backoff) until the request succeeds.

Free routes (GET /v1/whoami, GET /v1/balance) have per-key rate limits and may return 429 — see Errors.