# Credits (/docs/credits) Credits [#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](/docs/rate-limits.md)). How much does each request cost? [#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](/docs/endpoint-pricing.md). 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](/docs/endpoint-pricing.md) 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 [#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: | Cadence | Checks per day | Checks per month | Monthly cost at 2 credits/check | | --------------- | -------------- | ---------------- | ------------------------------- | | Every 5 minutes | 288 | \~8,640 | \~17,280 credits | | Every hour | 24 | \~720 | \~1,440 credits | | Every 24 hours | 1 | \~30 | \~60 credits | 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 [#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? [#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: ```json { "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? [#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](/docs/caching.md) page. Registry-marked uncached endpoints run and bill on every request. When are credits refunded? [#when-are-credits-refunded] Credits are automatically refunded when a paid request cannot complete successfully: | Scenario | Status | Refund | | --------------------------------------------------------- | ------------------------- | ------------------- | | Upstream platform error | 502 `UPSTREAM_ERROR` | ✅ | | Upstream timeout | 504 `UPSTREAM_ERROR` | ✅ | | Upstream rate-limited (over our provider quota) | 503 `SERVICE_UNAVAILABLE` | ✅ | | Circuit breaker open | 503 `SERVICE_UNAVAILABLE` | ✅ | | Internal server error | 500 `INTERNAL_ERROR` | ✅ | | Empty upstream body (nonexistent handle, etc.) | 404 `RESOURCE_NOT_FOUND` | ✅ | | Client-side errors (400/401/402/404 `ENDPOINT_NOT_FOUND`) | 4xx | No charge to refund | | 405 / 409 / 422 | 4xx | No charge to refund | 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 [#idempotent-retries-dont-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](/docs/response-schema.md) for headers and the [Error Handling](/docs/errors.md) page for conflict behaviour. Topping up [#topping-up] Buy credit packs in Dashboard → Billing. Packs are one-time purchases (no subscriptions): | Plan | Credits | Price | | ---------- | ------- | ----------------- | | Free | 100 | £0 (signup bonus) | | Starter | 2,500 | £15 | | Growth | 20,000 | £49 | | Pro | 150,000 | £299 | | Enterprise | Custom | Contact us | Credits do not expire. Every purchase, deduction, refund, and bonus is recorded on your transaction history.