# Credits (/docs/credits)

How credit billing works. Tiers, the welcome bonus, free cache hits, automatic refunds, and monitor costs

Every request costs credits based on the endpoint's tier. New accounts get 100 free credits, cache hits cost nothing, and a request that fails on our side or upstream is refunded automatically. Billing is pay as you go: there is no subscription, and credits do not expire.

## What does a request cost?

[Endpoint pricing](/docs/endpoint-pricing.md) publishes the exact figure for every individual endpoint.

### Endpoints that are not on the ladder

Composite and metered endpoints carry their own price and can bill well above the premium tier.

| Endpoint                                               | Cost                                                                                      |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `/v1/prism/brand-mentions`                             | Flat 50 credits                                                                           |
| `/v1/prism/leads`                                      | Flat 50 credits                                                                           |
| `/v1/prism/ai-visibility`                              | 2 to 1,605 credits, depending on how many prompts, runs, and engines you ask for          |
| `/v1/prism/comments`                                   | Metered per comment page for most sources, but a flat 5 credits for an Instagram post URL |
| `POST /v1/youtube/videos`, `POST /v1/youtube/channels` | 5 credits per 50 ids                                                                      |

Check [Endpoint pricing](/docs/endpoint-pricing.md) for the exact figure or range rather than assuming a tier.

A metered endpoint deducts its upper bound when the request is dispatched, then refunds the difference the moment the real cost is known. `credits_used` on a metered call is often lower than the deduction you saw. A few of them also carry per-input rules that a published range cannot express, so read the endpoint's own page before you budget for it.

## Web monitors are the one charge that repeats

Every price above is per request. You call, you pay once, and nothing else happens. Web monitors are the exception.

Creating a monitor 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.

| 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 drains 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 what is currently running with `GET /v1/web/monitors`.

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 balance?

Three ways, depending on context.

1. **On the response.** 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. **From the meta endpoint.** `GET /v1/credits/balance` costs 0 credits and takes API-key auth. It returns the balance plus a summary of recent deductions.
3. **In the dashboard.** The Usage and Activity Logs pages show balance, history, and per-endpoint breakdowns.

```json title="Response"
{
  "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
}
```

## 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. See [Caching](/docs/caching.md) for the freshness window per data type, the shared-across-account model, and how to force a guaranteed-live fetch. Endpoints marked uncached run and bill on every request.

## When are credits refunded?

Credits are refunded automatically 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.

A few list endpoints sell an opt-in row join, such as `include=profile` on the LinkedIn people lanes. The join holds its per-row price for the whole page up front and keeps it only for the rows it actually filled: rows served from cache cost nothing, and rows it could not fill are refunded. The response carries a `hydration` block itemising the rows, the rows filled, the rows served from cache, and the credits held against the credits kept.

Composite endpoints refund proportionally when only some legs produce. The batch-by-id endpoints are the exception: `POST /v1/youtube/videos` and `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.

## Labels add no credits

The SocialCrawl [labels](/docs/labels.md) that comment, post, review and search lists carry by default never add credits, holds or refunds. A call costs exactly what the same call costs with `judgments=off`, and `data.labels.extra_credits` is `0`. Asking by name for a label that is also a default one, such as `label=sentiment`, is free too, and so is `relevance=filter` with your query as the topic.

Only labels that need your own input, or that are not yet measured well enough to be defaults, are metered: `label=mention&brand=`, `label=intent&offer=`, `label=spam`, `toxic` or `low_quality` on comments, `label=reports&reports=` and `label=incentivized` on reviews, and `relevant_to=` on search relevance. Each holds a few credits up front and settles at 1 credit per started 25 rows newly judged on that request; rows already judged for anyone, a page where nothing could be judged, and a cached page cost nothing extra. `brief=` on `/v1/search/creators` adds 2 credits.

## Idempotent retries do not 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 the headers, and [Error handling](/docs/errors.md#idempotency) for conflict behavior.

## Topping up

Buy credit packs in **Dashboard → Billing**. Packs are one-time purchases, not 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.

## Next steps

- [Endpoint pricing](/docs/endpoint-pricing.md): The exact credit cost of every endpoint.
- [Caching](/docs/caching.md): Freshness windows, and how cache hits keep your bill down.
- [Error handling](/docs/errors.md): Refund rules per error code, and safe retry loops.
- [Rate limits](/docs/rate-limits.md): 600 requests per minute and 50 concurrent requests per key.