Credits

Most lookup endpoints consume credits. When the balance runs out, those routes return 402.

Social Fetch is pay-as-you-go by default — buy credit packs and spend them whenever. PAYG credits never expire. Optional subscription plans add included credits each month. 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 the same lookup; 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 balance before high-volume jobs with GET /v1/balance (or your own ledger).
• Treat 402 as a signal — top up, throttle, or pause.
• Reconcile against meta.creditsCharged so accounting matches what 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. On monthly plans, unused included credits do not roll over. On annual plans, they carry into the next month, up to one month's allowance, so you can hold at most two months' worth. 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.

Free credits for adding a card

If you have not bought anything yet, save a card in billing and claim 250 free credits. Nothing is charged until you buy. One bonus per person and card; prepaid cards do not qualify. A 402 insufficient_credits response carries the link as cardBonusUrl.

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.

Add-ons

Credits, plans, and payment methods belong to a workspace and are billed to it. You can own up to 5 shared workspaces in addition to your personal workspace. Credits cannot be transferred between workspaces; if you bought credits in the wrong workspace, contact us and we can move them on request. Remaining credits are forfeited when a workspace is closed and its 30-day restoration window ends.

Add-ons are flat monthly extras you can put on a paid plan. Prices are per workspace, and annual billing is 10% cheaper than twelve months.

• Building on the data. You do not need an add-on to build Social Fetch data into your own product and sell it to your customers. Every plan allows it under our Terms.
• Priority support and the shared Slack channel. Both are available on any paid plan that does not already include them. Priority support is included from Growth, and the shared Slack channel is included on Scale.
• Who can buy. Workspace owners and the Billing role.
• Where. Billing → Add-ons in the dashboard. Adding one is self-serve and takes effect straight away.
• Billing. An add-on rides on your plan's subscription: same invoice, same renewal date. When you add one mid-period you are charged a prorated amount for the rest of the period.
• Removing. Remove an add-on any time from the same page. A prorated credit is applied. Add-ons also stop when the plan ends.
• Changing plans. Remove an add-on before downgrading to a plan it is not sold on. Upgrading is unaffected.
• Pay as you go. Add-ons need an active paid plan (Starter or higher), so they are not available on pay-as-you-go alone.

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, up to 200 in flight per workspace.

Under load, requests may be queued. Under extreme concurrency, or above the in-flight limit (concurrency_limit), 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.