Credits

SocialCrawl uses a credit-based, pay-as-you-go billing model. Every request costs credits based on the endpoint's tier. Per API key there is a generous 600 requests/minute window and a concurrency ceiling of 50 simultaneous requests (see Rate Limits).

How much does each request cost?

For the cost of every individual endpoint — including bundle endpoints like /v1/search/everywhere that use a flat fee — see Endpoint pricing.

Not every endpoint sits on that ladder. Composite and metered endpoints carry their own price and can bill well above the premium tier: /v1/prism/brand-mentions and /v1/prism/leads are a flat 50 credits, and a metered endpoint bills a per-request range — the YouTube batch endpoints charge 5 credits per 50 ids, and /v1/prism/ai-visibility runs from 2 credits to 1,605 depending on how many prompts, runs, and engines you ask for. Endpoint pricing publishes the exact figure or range for every endpoint; check it there rather than assuming a tier.

A metered endpoint deducts its upper bound when the request is dispatched and refunds the difference the moment the real cost is known, so credits_used on a metered call is often lower than the deduction you saw. A few of them also carry per-input rules the range can't express — /v1/prism/comments is metered per comment page for most sources but a flat 5 credits for an Instagram post URL, whatever max and replies you pass.

The one charge that repeats

Every price above is per request: you call, you pay once, nothing else happens. Web monitors are the exception. Creating one costs 0 credits, but a monitor is a standing instruction, and every scheduled check it runs afterwards is billed:

Each check costs the endpoint's own upstream cost, plus 1 credit for orchestration. A monitor watching a page that costs 1 credit to scrape bills 2 credits per check.

That repeats on the cadence_minutes you set — as tight as every 5 minutes, or any whole number of hours up to 1440 (daily) — and it keeps repeating until you pause or delete the monitor. Nobody has to be logged in, and no further API calls are needed on your side.

Do the arithmetic before you leave one running:

A 5-minute monitor on a 1-credit page will drain the 100-credit welcome bonus in under four hours. Reach for the tightest cadence only when you genuinely need it.

The create response tells you what a single check costs: credits_booked is the upstream cost, so your real monthly figure is (credits_booked + 1) × checks per month. List your monitors with GET /v1/web/monitors to see what is currently running.

If your balance runs out, checks are not queued and nothing goes negative: the check is recorded as skipped at 0 credits, the schedule moves on to the next slot, and the monitor stays active — so it resumes on its own once you top up.

Welcome bonus

Every new account receives 100 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. API responses normally include both body credits_remaining and an X-Credits-Remaining header. If an idempotency replay has a transient balance lookup failure, the body value is null and the header is omitted.

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. A response served from cache ("cached": true, X-Cache: HIT) costs 0 credits: no transaction row is written and your balance is unchanged. We already paid the upstream cost when we fetched the original, so charging you again for the same data would be double-billing.

Caching is on by default for cache-enabled endpoints and is the single biggest lever for keeping your bill down. For the freshness windows per data type, the shared-across-account model, and how to force a guaranteed-live fetch when you need one, see the Caching page. Registry-marked uncached endpoints run and bill on every request.

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.

There is one more refund you will see on a successful call: metered endpoints deduct an upper-bound ceiling up front and refund the difference as soon as the real cost is known, so a 200 can come back with credits_used lower than the deduction. Composite endpoints refund proportionally when only some legs produce, with one exception — the batch-by-id endpoints (POST /v1/youtube/videos, POST /v1/youtube/channels) bill per 50-id chunk however many ids resolve, so there is no per-id refund. A batch that resolves nothing is still refunded in full.

Idempotent retries don't double-charge

If you send an Idempotency-Key header, we guarantee a single charge per key. A replay keeps the cached payload immutable except for billing metadata: credits_used becomes 0 and idempotent_replay becomes true. A known current balance refreshes body credits_remaining and the X-Credits-Remaining header; no balance row resolves to 0. On a transient lookup failure, body credits_remaining is null and X-Credits-Remaining is omitted. 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.