Credits

SocialCrawl uses a credit-based, pay-as-you-go billing model. Every request costs credits based on the endpoint's tier. No time-based rate limits — just a concurrency ceiling of 50 simultaneous requests per API key.

How much does each request cost?

Welcome bonus

Every new account receives 400 free credits on signup — enough to try every standard endpoint without attaching a payment method. The bonus appears in your transaction history as a bonus entry.

How do I check my credit balance?

Three ways, depending on context:

1. Every API response includes credits_remaining and an X-Credits-Remaining header

2. Meta endpoint — GET /v1/credits/balance (0 credits, API-key auth) returns the balance plus a summary of recent deductions:

   {
     "success": true,
     "platform": "meta",
     "endpoint": "/v1/credits/balance",
     "data": {
       "balance": 8432,
       "recent_deductions": { "last_24h": 128, "last_7d": 1043 }
     },
     "credits_used": 0,
     "credits_remaining": 8432,
     "request_id": "req-abc123",
     "cached": false
   }

3. Dashboard — Usage and Activity Logs pages show balance, history, and per-endpoint breakdowns

Are cache hits free?

Yes. When a response is served from cache ("cached": true, X-Cache: HIT), you are charged 0 credits. We already paid the upstream cost when we fetched the original — billing you a second time would double-charge the same data. No transaction row is written and your balance stays unchanged.

When are credits refunded?

Credits are automatically refunded when a paid request cannot complete successfully:

Refunds happen atomically inside the router — your balance is restored before the error envelope returns.

Idempotent retries don't double-charge

If you send an Idempotency-Key header, we guarantee a single charge per key. Replayed requests return the original response verbatim, deduct 0 new credits, and include X-Idempotent-Replay: true. See Response Schema for headers and the Error Handling page for conflict behaviour.

Topping up

Buy credit packs in Dashboard → Billing. Packs are one-time purchases (no subscriptions):

Credits do not expire. Every purchase, deduction, refund, and bonus is recorded on your transaction history.