Bring your own tool keys | Docs

# Bring your own tool keys

> Add your own tool provider keys, and how calls on them are billed.

You can run tool calls on your own account with a tool provider by adding its API key to Clonvo. Calls on your key run under that provider’s pricing and terms, and Clonvo still gives you one result shape per tool, routing between your keys, usage tracking and spending limits. Without a key, calls run on Clonvo credits (see [Tool billing](https://clonvo.com/docs/tool-billing.md)).

> **Note: Available from Pay as you go up**
> 
> On Free, tool calls fail with `402`, even if you’ve added keys. Buy credits of any amount to move to Pay as you go.

## Supported providers

| Provider | Provider id | Get a key |
| --- | --- | --- |
| Firecrawl | `firecrawl` | [firecrawl.dev](https://www.firecrawl.dev/app/api-keys) |
| Tavily | `tavily` | [app.tavily.com](https://app.tavily.com/home) |
| Exa | `exa` | [dashboard.exa.ai](https://dashboard.exa.ai/api-keys) |
| Parallel | `parallel` | [platform.parallel.ai](https://platform.parallel.ai) |
| TinyFish | `tinyfish` | [agent.tinyfish.ai](https://agent.tinyfish.ai/api-keys) |

One provider is enough; add more to have fallbacks. A key is used only for the tools its provider serves: `GET /v1/tools` lists, for each tool, the providers that can serve it in `providers` and the ones you can use now in `available_providers`.

### Provider ids

The provider ids above appear in a response’s `provider` for a call on your key, and you can use them in a call’s [`provider` object](https://clonvo.com/docs/tool-routing.md) (`order`, `only` and `ignore`). Calls on Clonvo credits use `clonvo`.

## Adding your keys

1.  Create an API key with your provider, using the links above.
2.  In the Clonvo dashboard, open **Provider keys** and add it under **Tools**. You need to be an owner or admin of the organization. Clonvo checks Firecrawl, Tavily, Parallel and TinyFish keys before saving them, without spending your credits. Exa has no way to check a key for free, so Exa keys are saved unchecked and your first call shows whether the key works.
3.  Call a tool with your Clonvo API key. Nothing changes in your code.

Keys are encrypted at rest and shown only in masked form after you save them, as for [model provider keys](https://clonvo.com/docs/byok.md#adding-a-key). They belong to the organization and are used for calls from all its projects.

## How your keys are used

Tool keys work like [model keys](https://clonvo.com/docs/byok.md), with two differences:

-   Clonvo tries your tool keys first, provider by provider. When they all fail with an error worth retrying, or you have none, the call runs on Clonvo credits, unless you exclude `clonvo` in the call’s [`provider` settings](https://clonvo.com/docs/tool-routing.md).
-   **Always use this key** on a tool key stops Clonvo from moving on to another tool provider, or to Clonvo credits, when that key fails.

With several keys for one provider, Clonvo tries them oldest first, as for [model keys](https://clonvo.com/docs/byok.md#how-requests-are-routed). A key the provider rejects shows the error under **Provider keys**. See [Tool routing](https://clonvo.com/docs/tool-routing.md) for the full order and when Clonvo moves on.

## Billing on your keys

Your provider bills you for each call, if it charges for it. On Clonvo, a tool call on your key counts like a request on your own model key:

-   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).
-   Above the allowance, Clonvo deducts the BYOK fee, 4% of the list price, from your credits. Once you’re past the allowance with a balance of zero or less, calls on your keys fail with `402` and the code `byok_fee_requires_credits` until you buy credits.

The list price is what the call costs on your provider’s self-serve pricing. Where the provider reports what it charged, Clonvo uses that figure; otherwise it prices the call from its arguments and result. Prices were last checked on November 9, 2026.

Some providers don’t charge for some calls and limit how many you can make instead. Those calls have a list price of $0, so they never count toward your allowance or the BYOK fee. Past the provider’s limits it refuses the call, and Clonvo moves on to your next tool provider.

Each response reports both numbers in `usage`: `cost` is the list price, `charged` is what came out of your credits (`0` within the allowance), and `is_byok` is `true`. The response’s `provider` is your provider’s id. On Enterprise, the allowance and rate are agreed with your organization; see [Bring your own keys](https://clonvo.com/docs/byok.md#pricing).