# Control cost and credits

**Outcome:** predictable spend at scale, with no surprise `402`s in production.

## The five levers, in order of impact

### 1. Depth

A `deep_review` search costs **60 credits**; `standard` costs **5**. Nothing else you do matters as
much. Default to `standard` and escalate only when the cheap pass is genuinely thin — in practice
that is a small minority of questions.

### 2. `max_papers`

Lower ceilings cost less and return faster. Defaults are the tier maximum, so set it explicitly when
you only need a direction rather than a survey.

### 3. Caching

Reads are free, so cache the **resource**, not just your rendering of it. Key answers on the
normalized query plus depth, and honour the storage limits in content-licensing — generated
answers you may keep indefinitely; licensed full text you may not.

### 4. Idempotency

Every POST takes an `Idempotency-Key`. Without one, a retried request after a timeout is a second
charge. This is the cheapest bug to prevent and the most annoying to discover on an invoice.

### 5. Batching

One extraction over 500 documents costs 2 credits per source and one concurrency slot.
Five hundred single-source runs cost the same credits but 500 slots — you will hit
rate limits long before you finish.

## Worked example

A product answering 1,000 questions a day:

| Mix | Credits/day | Credits/month |
|---|---|---|
| All `standard` (5) | 5,000 | 150,000 |
| 90% standard, 10% `deep_review` (60) | 10,500 | 315,000 |
| All `deep_review` | 60,000 | 1,800,000 |

At $10 per 1,000 credits, the middle row is roughly $3,150/month and the last is $18,000 — from one
default value. Make depth a product decision, not a default.

## Guardrails to put in before launch

- **Per-key monthly caps** so a batch job cannot starve production (api-keys)
- **Alert on `X-Credits-Remaining`** at 20% and 5% of your monthly grant
- **Daily reconciliation** against usage with `group_by[]=endpoint&group_by[]=api_key`
- **Handle `402` as a product state**, not a 500 — degrade to cached or `standard` results
- **Cap agent loops.** An LLM with a `search_literature` tool and no budget will spend it

## Measuring

`X-Credits-Cost` is authoritative per call. `/v1/usage` is the daily record and may lag live traffic by
up to five minutes, so reconcile daily rather than per request.

## Related

credit · usage · depth · pricing-and-credits · rate-limits