> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pramaan.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Prices and limits

> See what a request will cost before it runs, cap its price, and ask for a second opinion.

Prices are in micro-USD: 1,000,000 is one US dollar. Every response carries
`X-Pramaan-Price-Micro`, what that call cost you.

## Estimate a request

Send the body you would send to the capability to its `estimate` route. Nothing runs and
nothing is charged.

```bash theme={null}
curl https://api.pramaan.dev/v1/capabilities/web.crawl/estimate \
  -H "Authorization: Bearer $PRAMAAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "limit": 50}'
```

```json theme={null}
{ "price_max_micro": 65000, "balance_micro": 1000000, "can_run": true }
```

| Field | Meaning |
| - | - |
| `price_max_micro` | The most this request can be charged. The real price is often lower. |
| `balance_micro` | Your credit now. |
| `can_run` | Whether it would run now. |
| `reason` | Only when `can_run` is false: `balance` (top up), `daily_cap` (raise your daily cap) or `price_ceiling` (see below). |

```ts theme={null}
const estimate = await p.capabilities.estimate("web.crawl", { url: "https://example.com", limit: 50 });
if (estimate.canRun) await p.call("web.crawl", { url: "https://example.com", limit: 50 });
```

The estimate grows with what you ask for. For some capabilities, a crawl for example, each
result is priced on its own, and the estimate is for all `limit` of them. For others the
estimate is the price of one call, and the real price can be higher when more comes back.

## Credit set aside while a request runs

Before a job starts, and before any single call that could cost \$0.50 or more, the estimate is
set aside from your credit. This is not a charge. When the request ends you pay its real price
and the rest comes back. `GET /v1/balance` shows what is set aside as `held_micro`.

If your balance or your daily spend cap cannot cover the estimate, the request is refused with
`402 spend_cap_reached` before anything runs. The error says which limit (`reason`) and how
much is needed (`required_micro`).

## Cap the price of one request

Some capabilities have a price ceiling: the most one call is ever priced at. It is shown as
`price_ceiling_micro` in `GET /v1/capabilities`. Data sources that could cost more are not used.

To set your own limit for one request, send `Pramaan-Max-Price-Micro` (a whole number of
micro-USD above 0). It replaces the capability's ceiling for that request, whether lower or
higher:

```ts theme={null}
await p.run("web.search", { query: "open source CRM" }, { maxPriceMicro: 20_000 });
```

When no data source fits under the limit, the request fails with `400 invalid_request` and the
message names the lowest limit that would work. The same value comes back from the estimate as
`price_max_micro` with `reason: "price_ceiling"`.

The limit chooses which data sources may answer and how much is set aside. Where a data source
states its worst case for a request up front, you are never charged more than the estimate.

## Ask for a second opinion

Some answers are honest but weak. `people.email.verify` may say `accept_all` (the domain accepts
every address, so this one cannot be confirmed) or `unknown`. Send
`Pramaan-Second-Opinion: true` to have one more source asked when that happens:

```ts theme={null}
const check = await p.run("people.email.verify", { email: "jane@example.com" }, { secondOpinion: true });
```

* A firm second answer replaces the first. Otherwise you get the first answer unchanged.
* You pay for each source that answered. The estimate includes both.
* The response header `X-Pramaan-Second-Opinion: used` tells you a second source was asked.
* Without the header nothing changes: one source, one price.

`people.email.verify` also returns `risk` when an address should not be mailed even though it
may accept mail: `disposable`, `spam_trap`, `do_not_mail` or `other`. An answer with a `risk` is
final, so no second opinion is asked for it.

## What is free

* A call that fails, a job that fails and a job stopped at its time limit.
* A capability that runs on your own [connected account](https://docs.pramaan.dev/guides/connections.md).
* Uploading a [file](https://docs.pramaan.dev/guides/files.md).

A job you cancel is charged for the work already done, never more than what was set aside (see
[jobs](https://docs.pramaan.dev/guides/jobs.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.