# Tool billing

> How tool calls are billed on your own keys and on Clonvo credits: list prices, caps and holds.

How a tool call is billed depends on what served it. `provider` in the response says which: `clonvo` for a call on Clonvo credits, or one of [your own providers](https://clonvo.com/docs/tool-keys.md#provider-ids) for a call on your key. `usage.is_byok` is `true` only for a call on your own key.

| Field | On your own key | On Clonvo credits |
| --- | --- | --- |
| `usage.cost` | The call’s list price on your provider’s self-serve pricing | Clonvo’s price for the call |
| `usage.charged` | `0` within your BYOK allowance, then the BYOK fee | `cost` plus 2% |
| `usage.is_byok` | `true` | `false` |

## On your own keys

Your provider bills you for each call, if it charges for it. On Clonvo, its list price counts toward your organization’s free BYOK allowance ($25,000 of list-price usage a month on Pay as you go, shared with your model keys), and above the allowance Clonvo deducts the BYOK fee, 4% of the list price, from your credits. See [Bring your own tool keys](https://clonvo.com/docs/tool-keys.md#billing-on-your-keys).

## On Clonvo credits

When none of your keys can serve a call, it runs on Clonvo credits. Most calls cost a fraction of a cent, and company and people lookups are often priced per result returned.

-   `usage.cost` is Clonvo’s price for the call in USD.
-   `usage.charged` is `cost` plus 2%, and comes out of your credits. `usage.is_byok` is `false`.
-   Clonvo caps the call’s cost at $0.05 for a search and $0.02 for a page read, plus $0.02 for each page `include_content` reads; the other tools’ caps are in the table below. While the call runs, Clonvo holds that cap plus 2% of your balance ($0.051 for a search, $0.0204 for a page read), and releases what the call didn’t use.
-   When your balance (after requests still in progress) or the API key’s remaining limit can’t cover that hold, Clonvo doesn’t refuse the call: it lowers the cap, page reads included, to what your credits can pay for, so the call can’t cost more than that. Most calls cost far less than the full cap and still go through. If the call can’t be served within the lower cap, it fails with `402` and isn’t charged.
-   The cap goes no lower than $0.005 for a search and $0.002 for a page read (a hold of $0.0051 and $0.00204). If your credits can’t cover even that, the call fails with `402`, and the message says the least it needs.
-   Your balance needs to be above zero, and an API key’s [spending limit](https://clonvo.com/docs/authentication.md) applies as for model requests.
-   A call that fails isn’t charged to your credits. A lookup that finds nothing (`company: null`, an empty list) is an answer, and can still cost something, since some providers charge for a miss.

| Tool | Cap per call | Credits held | Lowest cap |
| --- | --- | --- | --- |
| `web_search` | $0.05 | $0.051 | $0.005 |
| `web_scrape` | $0.02 | $0.0204 | $0.002 |
| `web_map` | $0.02 | $0.0204 | $0.002 |
| `web_extract` | $0.04 | $0.0408 | $0.011 |
| `web_answer` | $0.02 | $0.0204 | $0.006 |
| `find_similar` | $0.03 | $0.0306 | $0.008 |
| `company_search` | $0.02 + $0.01 per result asked for | $0.0204 + $0.0102 per result | $0.005 |
| `company_enrich` | $0.03 | $0.0306 | $0.002 |
| `company_news` | $0.06 | $0.0612 | $0.011 |
| `company_jobs` | $0.02 + $0.03 per result asked for | $0.0204 + $0.0306 per result | $0.01 |
| `company_similar` | $0.2 | $0.204 | $0.01 |
| `people_search` | $0.02 + $0.01 per result asked for | $0.0204 + $0.0102 per result | $0.005 |
| `people_enrich` | $0.03 | $0.0306 | $0.002 |
| `web_crawl` | $0.01 + $0.006 per result asked for | $0.0102 + $0.00612 per result | $0.01 |

Calls on Clonvo credits never count toward your BYOK allowance.

## Research and browser tasks on credits

`web_research` and `browser_task` on Clonvo credits are billed for what the job used, up to a hold Clonvo takes before it starts. Your own keys are still tried first.

-   Before the job starts, Clonvo holds the most it can cost, plus 2%, from your balance: for research, the price for the `depth` you asked for (`deep` costs more than `standard`); for a browser task, the price of `max_steps` steps (30 by default).
-   When the job ends, `usage.cost` is the job’s cost and `usage.charged` is that plus 2%. The charge is never more than the hold, and whatever the job didn’t use goes back to your balance.
-   A browser task is billed for the steps the agent took. If it reaches `max_steps` without finishing, Clonvo stops it, and it fails with `step_limit_reached` and is charged for `max_steps`.
-   If your balance (after requests still in progress) or the API key’s remaining limit can’t cover the hold, the call fails with `402` before the job starts. Lower `max_steps` or choose standard `depth` to need less.
-   A cancelled or timed-out job is charged what it still costs: the steps a browser task took, the research done so far, or the full price of a research run that can’t be stopped once started.

## Jobs

A [job](https://clonvo.com/docs/jobs.md) is billed once, when it ends, like any tool call. Clonvo holds credits for the most it can be charged from the start, until the job ends.

## In your activity

Each call’s cost and charge appear in **Activity**, where tool calls carry a **Tool** tag. Calls on Clonvo credits show **Credits** as the billing. See [Credits and billing](https://clonvo.com/docs/credits.md) for buying credits and how request costs are reported.