Prices and limits

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.

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}'

{ "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).

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:

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:

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.
Uploading a file.

A job you cancel is charged for the work already done, never more than what was set aside (see jobs).

Get started

Guides

Tools

Prices and limits

Estimate a request

Credit set aside while a request runs

Cap the price of one request

Ask for a second opinion

What is free

​Estimate a request

​Credit set aside while a request runs

​Cap the price of one request

​Ask for a second opinion

​What is free

Estimate a request

Credit set aside while a request runs

Cap the price of one request

Ask for a second opinion

What is free