# Tools

> Web search, scraping, crawling, research, a browser agent, and company and people data for agents, on your own Firecrawl, Tavily, Exa, Parallel or TinyFish key, or on Clonvo credits.

Clonvo gives your agents web, company and people tools behind the same API key you use for models: search the web, read, map and crawl sites, extract typed data from a page, get cited answers and research reports, run a browser agent, and look up companies and professional profiles. Call them over REST, or connect any MCP client to Clonvo’s [MCP server](https://clonvo.com/docs/mcp.md).

A call runs on your own Firecrawl, Tavily, Exa, Parallel or TinyFish key when you’ve added one under **Provider keys** and that provider serves the tool. Without one, it runs on Clonvo credits, powered by [treg](https://treg.to)’s provider routing: Clonvo sends the call to treg, treg picks a provider for it, and your credits pay the call’s cost plus 2%. Your own keys are always tried first. Either way you get one result shape per tool, whichever provider served the call. `company_enrich`, `company_news`, `company_jobs` and `people_enrich` run on Clonvo credits only. treg doesn’t serve `web_research` or `browser_task`, so on credits those run on Clonvo’s own Parallel, Exa and TinyFish keys instead; see [Research and browser tasks on credits](#research-and-browser-tasks-on-credits).

> **Note: Available from Pay as you go up**
> 
> Tools need Pay as you go or higher: calls on your own keys work like [bring your own keys](https://clonvo.com/docs/byok.md) for models, and calls on Clonvo credits need credits to pay for them. On Free, tool calls fail with `402`. Buy credits of any amount to move to Pay as you go.

## Available tools

| Tool | What it does | Providers, in default order |
| --- | --- | --- |
| `web_search` | Searches the web and returns ranked pages with title, URL and a snippet, and optionally each page’s content. category narrows it to news, companies, people, research papers, GitHub, PDFs or financial reports. | Tavily, Exa, TinyFish, Parallel, Firecrawl, then treg on Clonvo credits |
| `web_scrape` | Reads one page and returns its content as markdown or plain text, with the title. | Firecrawl, TinyFish, Parallel, Tavily, Exa, then treg on Clonvo credits |
| `web_map` | Lists a site’s URLs, with titles where the provider has them. | Firecrawl, Tavily, then treg on Clonvo credits |
| `web_extract` | Reads one page and returns typed JSON shaped by your JSON Schema. | Firecrawl, then treg on Clonvo credits |
| `web_answer` | Answers a question from current web sources, with citations. | Exa, Tavily, Parallel, then treg on Clonvo credits |
| `find_similar` | Finds pages similar to a URL, in web_search’s result shape. | Exa, then treg on Clonvo credits |
| `company_search` | Finds companies by description, industry or technology. | Exa, Parallel, then treg on Clonvo credits |
| `company_enrich` | Looks up one company by domain, LinkedIn URL or name. | treg on Clonvo credits |
| `company_news` | Recent news about a company, by domain. | treg on Clonvo credits |
| `company_jobs` | A company’s open job postings, by domain or name. | treg on Clonvo credits |
| `company_similar` | Companies similar to one you name by domain. | Exa, then treg on Clonvo credits |
| `people_search` | Finds professional profiles by role, company, name or description. | Exa, Parallel, then treg on Clonvo credits |
| `people_enrich` | Looks up one professional profile from a LinkedIn URL. | treg on Clonvo credits |
| `web_crawl` | Reads many pages of a site as markdown. Runs as a job. | Firecrawl, Tavily, then treg on Clonvo credits |
| `web_research` | Researches a question across many sources and writes a cited report. Runs as a job. | Exa, Parallel |
| `browser_task` | A browser agent works through a page to reach a goal. Runs as a job. | TinyFish |

Each tool takes the same arguments whichever provider serves it. `GET /v1/tools` and the MCP server return each tool’s JSON Schema, which you can pass straight to a model as a function definition.

### web_search

| Argument | Type | Description |
| --- | --- | --- |
| `query` (Required) | `string` | What to search for: a question or keywords. |
| `max_results` | `integer` | How many results to return (1–20, default 5). |
| `category` | `"news" \| "company" \| "people" \| "research_paper" \| "github" \| "pdf" \| "financial_report"` | Search one kind of page: "news" (articles), "company" (company websites and profiles), "people" (LinkedIn-style profiles), "research_paper", "github" (repositories and code), "pdf" (PDF documents) or "financial_report" (filings and reports). Only providers that support the category serve the call. |
| `include_domains` | `string[]` | Only return results from these domains, e.g. \["arxiv.org", "nature.com"\]. |
| `exclude_domains` | `string[]` | Never return results from these domains. |
| `time_range` | `"day" \| "week" \| "month" \| "year"` | Only return pages published within the last day, week, month or year. |
| `include_content` | `boolean` | Also return each result’s page content (markdown or plain text) in content, up to max_content_chars. Snippets stay at most 500 characters either way. Slower and costs more on some providers. |
| `max_content_chars` | `integer` | With include_content, the most characters of content to return per result (default 5,000). |

With `category`, only the providers that support that kind of search serve the call:

| `category` | Providers |
| --- | --- |
| `news` | Tavily (news topic), Exa, Firecrawl (news source), then treg’s news search |
| `company`, `people` | Exa, Parallel (entity search), then Exa through treg |
| `research_paper` | Exa, Firecrawl (research category), then Exa through treg |
| `financial_report` | Tavily (finance topic), Exa, then Exa through treg |
| `pdf` | Firecrawl only, on your own key |
| `github` | Every provider: Clonvo limits the results to github.com |

If none of your keys serves the category and Clonvo credits can’t either, the call fails with `tool_requires_own_key` and names the providers that can.

### web_scrape

| Argument | Type | Description |
| --- | --- | --- |
| `url` (Required) | `string` | The http(s) URL of the page to read. |
| `format` | `"markdown" \| "text"` | Output format: "markdown" (default) or "text". |
| `only_main_content` | `boolean` | Return only the main content, without navigation, headers, footers and ads (default true). |
| `max_chars` | `integer` | The most characters of content to return (default 50,000); longer pages are cut and marked truncated. |

### web_map

| Argument | Type | Description |
| --- | --- | --- |
| `url` (Required) | `string` | The site to map: its home page or any page on it. |
| `search` | `string` | Only or first the URLs about this, e.g. "pricing" or "API reference". |
| `max_results` | `integer` | How many URLs to return (1–1000, default 100). |
| `include_subdomains` | `boolean` | Also list URLs on the site’s subdomains (default false). |

### web_extract

| Argument | Type | Description |
| --- | --- | --- |
| `url` (Required) | `string` | The http(s) URL of the page to extract from. |
| `schema` (Required) | `object` | JSON Schema of the data to return, with "type": "object" at the top, e.g. {"type": "object", "properties": {"price": {"type": "number"}}}. Use arrays of objects for lists. |
| `prompt` | `string` | What to extract, in words, when the schema alone doesn’t say it. |

`data` in the result has the shape your schema describes. Providers fill what the page has, so a field the page doesn’t show can be missing or `null`.

### web_answer

| Argument | Type | Description |
| --- | --- | --- |
| `query` (Required) | `string` | The question to answer. |

### find_similar

| Argument | Type | Description |
| --- | --- | --- |
| `url` (Required) | `string` | The page to find similar pages to. |
| `max_results` | `integer` | How many results to return (1–20, default 5). |
| `exclude_source_domain` | `boolean` | Leave out pages on the URL’s own domain (default true). |
| `include_domains` | `string[]` | Only return results from these domains. |
| `exclude_domains` | `string[]` | Never return results from these domains. |

### company_search

| Argument | Type | Description |
| --- | --- | --- |
| `query` | `string` | The companies to find, described in words. |
| `industry` | `string` | An industry, e.g. "fintech" or "biotechnology". |
| `technology` | `string` | A technology the companies use, e.g. "Snowflake" or "Shopify". |
| `country` | `string` | ISO 3166-1 alpha-2 country code, e.g. "US" or "DE". |
| `max_results` | `integer` | How many companies to return (1–25, default 10). |

### company_enrich

| Argument | Type | Description |
| --- | --- | --- |
| `domain` | `string` | The company’s website domain, e.g. stripe.com. Use a bare domain such as example.com (no scheme, path or wildcard). |
| `linkedin_url` | `string` | a LinkedIn company URL such as https://www.linkedin.com/company/stripe |
| `name` | `string` | The company’s name, when you have neither domain nor LinkedIn URL. |

### company_news

| Argument | Type | Description |
| --- | --- | --- |
| `domain` (Required) | `string` | The company’s website domain, e.g. stripe.com. Use a bare domain such as example.com (no scheme, path or wildcard). |
| `max_results` | `integer` | How many articles to return (1–25, default 10). |

### company_jobs

| Argument | Type | Description |
| --- | --- | --- |
| `domain` | `string` | The company’s website domain, e.g. stripe.com. Use a bare domain such as example.com (no scheme, path or wildcard). |
| `name` | `string` | The company’s name, when you don’t have its domain. |
| `max_results` | `integer` | How many job postings to return (1–25, default 10). |

### company_similar

| Argument | Type | Description |
| --- | --- | --- |
| `domain` (Required) | `string` | The company’s website domain, e.g. stripe.com. Use a bare domain such as example.com (no scheme, path or wildcard). |
| `max_results` | `integer` | How many companies to return (1–25, default 10). |

### people_search

| Argument | Type | Description |
| --- | --- | --- |
| `query` | `string` | The people to find, described in words: role, seniority, industry, place. |
| `company_domain` | `string` | Their employer’s website domain, e.g. stripe.com. Use a bare domain such as example.com (no scheme, path or wildcard). |
| `title` | `string` | A job title, e.g. "Head of Tax". |
| `name` | `string` | A person’s full name, to find their profile. |
| `location` | `string` | Where they are, e.g. "London, United Kingdom". |
| `keywords` | `string[]` | Skills or topics their profile should mention. |
| `max_results` | `integer` | How many people to return (1–25, default 10). |

### people_enrich

| Argument | Type | Description |
| --- | --- | --- |
| `linkedin_url` (Required) | `string` | a LinkedIn profile URL such as https://www.linkedin.com/in/jane-doe |

### web_crawl

| Argument | Type | Description |
| --- | --- | --- |
| `url` (Required) | `string` | Where to start crawling: a site or a section of it. |
| `max_pages` | `integer` | The most pages to read (1–100, default 10). Clonvo credits serve up to 20. |
| `include_paths` | `string[]` | Only crawl URL paths matching these regular expressions, e.g. \["^/docs/"\]. |
| `exclude_paths` | `string[]` | Skip URL paths matching these regular expressions. |
| `instructions` | `string` | What to look for, in words, e.g. "pages about authentication". Providers use it to pick pages. |
| `max_chars_per_page` | `integer` | The most characters of content per page (default 5,000). |

### web_research

| Argument | Type | Description |
| --- | --- | --- |
| `query` (Required) | `string` | The question or research brief. |
| `depth` | `"standard" \| "deep"` | "standard" (default) or "deep": deep reads more sources, takes longer and costs more. |
| `output_schema` | `object` | A JSON Schema with "type": "object" for structured output instead of a written report. |

### browser_task

| Argument | Type | Description |
| --- | --- | --- |
| `url` (Required) | `string` | The page the agent starts on. |
| `goal` (Required) | `string` | What the agent should do and return, e.g. "List the first 10 products with name and price". |
| `output_schema` | `object` | A JSON Schema with "type": "object" for the shape of the result. |
| `max_steps` | `integer` | The most steps (page actions) the agent may take (1–150, default 30). The run is billed per step and stops at this limit. |

`web_crawl`, `web_research` and `browser_task` can take minutes, so they run as [jobs](#long-running-tools).

Company tools return companies with the same fields whichever provider found them: `name`, `domain`, `website`, `description`, `industry`, `employees`, `location`, `founded` and `linkedin_url`, with `null` for what the provider doesn’t know. People tools return `name`, `title`, `company`, `company_domain`, `location`, `linkedin_url`, `url` and `summary`. Clonvo never returns email addresses or phone numbers, even when a provider sends them.

### Where providers differ

A provider that can’t honour an argument exactly still serves the call, and the result’s `notes` array says what it did instead.

For `web_search`:

-   **Firecrawl:** Firecrawl can’t combine include_domains and exclude_domains; when both are set, the exclusions are added to the query as -site: operators.
-   **Firecrawl:** time_range maps to Firecrawl’s tbs (qdr:d/w/m/y). Firecrawl web results carry no published date or score.
-   **Firecrawl:** category "news" searches Firecrawl’s news source, "research_paper" and "pdf" its research and pdf categories.
-   **Tavily:** category "news" and "financial_report" use Tavily’s news and finance topics.
-   **Exa:** time_range is applied as a start published date, so pages without a known date may be left out.
-   **Exa:** Exa results carry no relevance score.
-   **Exa:** For category "company" and "people", Exa takes no date filter, so time_range is ignored; for "people" Clonvo drops excluded domains from the results itself.
-   **Parallel:** Clonvo uses Parallel’s fast search mode. Snippets come from Parallel’s query-focused excerpts, with markup removed.
-   **Parallel:** Parallel ignores exclude_domains when include_domains is set, so Clonvo drops excluded domains from the results itself.
-   **Parallel:** time_range is sent as a start publication date. Parallel knows the date of few pages, so results can include undated pages. Parallel results carry no relevance score.
-   **Parallel:** include_content reads the results' pages with a second call to Parallel Extract, which costs $0.001 a page.
-   **Parallel:** category "company" and "people" use Parallel’s entity search ($0.005 a call): snippets are Parallel’s one-line descriptions, domain filters are applied by Clonvo, and time_range is ignored.
-   **TinyFish:** TinyFish returns 10 results per page, so asking for more than 10 makes two search requests. Results carry no relevance score.
-   **TinyFish:** include_content reads the results' pages with a second call to TinyFish Fetch, which counts toward its free daily allowance of 1,000 URLs.
-   **TinyFish:** Search is free up to 500 requests an hour (12,000 a day) and 30 a minute per account; past that TinyFish refuses the call and Clonvo moves to your next provider.
-   **treg:** treg picks the search provider (cheapest first, moving on when one fails or finds nothing), so snippets, dates and scores depend on the provider that served the call; served_by names it.
-   **treg:** include_domains and exclude_domains are added to the query as site: and -site: operators, and Clonvo drops results outside them, so a call can return fewer results than you asked for.
-   **treg:** time_range is applied by Clonvo to results with a known publication date; results without a date are kept.
-   **treg:** include_content reads results that came without page content through treg’s page extraction, billed as separate reads on the same call.
-   **treg:** category "news" uses treg’s news search; "company", "people", "research_paper" and "financial_report" use Exa’s search through treg.

For `web_scrape`:

-   **Firecrawl:** format "text" is derived from Firecrawl’s markdown by stripping markup.
-   **Tavily:** only_main_content: false is ignored (Tavily always extracts the main content).
-   **Exa:** format "markdown" returns Exa’s page text, which is close to markdown but not guaranteed.
-   **Exa:** only_main_content: false is ignored (Exa always extracts the main content).
-   **Parallel:** format "text" is derived from Parallel’s markdown by stripping markup. only_main_content: false is ignored.
-   **Parallel:** Parallel may return a recent indexed copy of the page instead of fetching it live.
-   **TinyFish:** format "text" is derived from TinyFish’s markdown by stripping markup. only_main_content: false is ignored (TinyFish always removes boilerplate).
-   **TinyFish:** Fetch is free up to 1,000 URLs a day per account; past that TinyFish refuses the call and Clonvo moves to your next provider.
-   **treg:** treg picks the provider that reads the page (cheapest first, moving on when one fails); served_by names it.
-   **treg:** format "text" is derived from the page markdown by stripping markup. only_main_content: false is ignored.

For `web_map`:

-   **Firecrawl:** search ranks the URLs by relevance; Firecrawl’s map costs one credit whatever its size.
-   **Tavily:** Tavily crawls from the URL (two levels deep) rather than reading a sitemap, and returns no titles.
-   **Tavily:** search is sent as Tavily crawl instructions, which doubles its price (2 credits per 10 URLs).
-   **treg:** treg picks the provider (cheapest first); titles are present only when that provider returns them.

For `web_extract`, `web_answer` and `find_similar`:

-   **Firecrawl:** Uses Firecrawl’s scrape with the JSON format (5 credits a page).
-   **treg:** treg picks the extraction provider (cheapest first); fields the page doesn’t have may be missing or null.

-   **Tavily:** The answer is Tavily’s basic answer from a basic search; citations are that search’s results.
-   **Parallel:** Uses Parallel’s Responses API on low effort ($0.01 a call), which takes 5–10 seconds.
-   **treg:** Uses Exa’s answer through treg.

-   **treg:** Uses Exa’s similar-page search through treg.

For the company and people tools:

-   **Exa:** Uses Exa’s search with category "company"; industry, technology and country are added to the query, and fields Exa has no data for are null.
-   **Parallel:** Uses Parallel’s entity search: each company has a name, website and one-line description; other fields are null, and country is added to the description.
-   **treg:** treg picks the data provider (cheapest first); field coverage depends on the provider, and a filter it can’t apply is listed in notes.

-   **Exa:** Uses two Exa searches with category "company": the company, then companies matching its description ($0.014). Lookalikes are looser than Ocean.io’s on Clonvo credits.
-   **treg:** treg tries Tomba, then Ocean.io, which returns 10 lookalikes for about $0.16 whatever max_results asks; Tomba bills a miss.

-   **treg:** Job boards bill per posting returned, so max_results sets the price.

-   **Exa:** Uses Exa’s search with category "people": the arguments are combined into one description, and fields Exa has no data for are null.
-   **Parallel:** Uses Parallel’s entity search: each person has a name, profile URL and one-line description; title, company and location are null.
-   **treg:** treg picks the data provider (cheapest first); a filter it can’t apply is listed in notes.

For the long-running tools:

-   **Firecrawl:** Runs in the background on Firecrawl (1 credit a page); instructions are sent as Firecrawl’s crawl prompt.
-   **Tavily:** Tavily crawls in one request of up to 150 seconds, so the job is finished when the call returns. It may return fewer pages than max_pages when the site has fewer links within two levels.
-   **treg:** Uses Tavily’s crawl through treg, which takes at most 20 pages; asking for more needs your own Firecrawl or Tavily key.

-   **Exa:** Uses Exa’s Agent API on "low" effort for standard ($0.025) and "medium" for deep ($0.10). Clonvo asks it not to look up contact details and removes any email address or phone number from the result.
-   **Parallel:** Uses Parallel’s Task API with the "base" processor for standard ($0.01) and "core" for deep ($0.025). Runs typically take one to three minutes. Parallel has no way to cancel a run.
-   **Parallel:** Without your own key, research runs on Clonvo credits through Clonvo’s Parallel key, then its Exa key.

-   **TinyFish:** Uses TinyFish’s web agent, which costs $0.016 per step. Clonvo sends max_steps as TinyFish’s step limit and also stops a run itself when it reaches it. Without your own key, it runs on Clonvo credits through Clonvo’s TinyFish key.
-   **TinyFish:** goal_reached is false when the agent ran but reported that it couldn’t do the task. Clonvo removes email addresses and phone numbers from the output.

## Adding your keys

1.  Create an API key with [Firecrawl](https://www.firecrawl.dev/app/api-keys), [Tavily](https://app.tavily.com/home), [Exa](https://dashboard.exa.ai/api-keys), [Parallel](https://platform.parallel.ai) or [TinyFish](https://agent.tinyfish.ai/api-keys). One provider is enough; add more to have fallbacks.
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.

Calls on your keys run on your own provider account, under that provider’s pricing and terms. Without a key, calls run on Clonvo credits instead (see [Billing](#billing)). 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).

## Billing

How a call is billed depends on what served it. `provider` in the response says which: one of your own-key providers, or `treg` for a call on Clonvo credits. `usage.is_byok` is `true` only for a call on your own key, so a `web_research` or `browser_task` job that ran on Clonvo’s own key shows that provider with `is_byok: false`.

### On your own 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.

The list price is what the call costs on the 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.

| Tool | Provider | List price |
| --- | --- | --- |
| `web_search` | [Firecrawl](https://docs.firecrawl.dev/billing) | 2 credits per 10 results, +1 credit per result with content; $0.0038/credit (Hobby plan) |
| `web_search` | [Tavily](https://docs.tavily.com/documentation/api-credits) | 1 credit (basic search) = $0.008 |
| `web_search` | [Exa](https://exa.ai/pricing) | $0.007 for up to 10 results (content included), +$0.001 per result above 10 |
| `web_search` | [Parallel](https://parallel.ai/pricing) | $0.001 for up to 10 results (fast mode), +$0.001 per result above 10, +$0.001 per result with content; company and people categories $0.005 |
| `web_search` | [TinyFish](https://www.tinyfish.ai/pricing) | Free: up to 500 searches an hour (12,000 a day), plus content reads within Fetch’s 1,000 URLs a day |
| `web_scrape` | [Firecrawl](https://docs.firecrawl.dev/billing) | 1 credit per page = $0.0038 |
| `web_scrape` | [Tavily](https://docs.tavily.com/documentation/api-credits) | 1 credit per 5 URLs (basic extract) = $0.0016 per page |
| `web_scrape` | [Exa](https://exa.ai/pricing) | $0.001 per page (text) |
| `web_scrape` | [Parallel](https://parallel.ai/pricing) | $0.001 per page (Extract) |
| `web_scrape` | [TinyFish](https://www.tinyfish.ai/pricing) | Free: up to 1,000 URLs a day |
| `web_map` | [Firecrawl](https://docs.firecrawl.dev/billing) | 1 credit per map = $0.0038 |
| `web_map` | [Tavily](https://docs.tavily.com/documentation/api-credits) | 1 credit per 10 URLs = $0.008 (2 credits with search) |
| `web_extract` | [Firecrawl](https://docs.firecrawl.dev/billing) | 5 credits per page (scrape + JSON) = $0.019 |
| `web_answer` | [Exa](https://exa.ai/pricing) | $0.005 per answer |
| `web_answer` | [Tavily](https://docs.tavily.com/documentation/api-credits) | 1 credit (basic search with answer) = $0.008 |
| `web_answer` | [Parallel](https://parallel.ai/pricing) | $0.01 per answer (Responses API, low effort) |
| `find_similar` | [Exa](https://exa.ai/pricing) | $0.007 for up to 10 results, +$0.001 per result above 10 |
| `company_search` | [Exa](https://exa.ai/pricing) | $0.007 for up to 10 results, +$0.001 per result above 10 |
| `company_search` | [Parallel](https://parallel.ai/pricing) | $0.005 per search (entity search) |
| `company_similar` | [Exa](https://exa.ai/pricing) | $0.007 for up to 10 results, +$0.001 per result above 10 |
| `people_search` | [Exa](https://exa.ai/pricing) | $0.007 for up to 10 results, +$0.001 per result above 10 |
| `people_search` | [Parallel](https://parallel.ai/pricing) | $0.005 per search (entity search) |
| `web_crawl` | [Firecrawl](https://docs.firecrawl.dev/billing) | 1 credit per page = $0.0038 |
| `web_crawl` | [Tavily](https://docs.tavily.com/documentation/api-credits) | 1 credit per 10 pages (2 with instructions) + 1 credit per 5 pages read; $0.008/credit |
| `web_research` | [Exa](https://exa.ai/pricing) | $0.025 standard (low effort), $0.10 deep (medium effort) |
| `web_research` | [Parallel](https://parallel.ai/pricing) | $0.01 standard (base), $0.025 deep (core); failed runs free |
| `browser_task` | [TinyFish](https://www.tinyfish.ai/pricing) | $0.016 per agent step (TinyAgent) |

TinyFish’s web agent, which serves `browser_task`, costs $0.016 per step the agent takes. TinyFish doesn’t charge for search or page reads. Instead it limits them: per account, about 500 searches an hour (12,000 a day, 30 a minute) and 1,000 page reads a day, resetting at 00:00 UTC. TinyFish calls have a list price of $0, so they never count toward your allowance or the BYOK fee. Past its limits TinyFish refuses the call, and Clonvo moves on to your next tool provider.

Each response reports both numbers in `usage`: `cost` is the list price and `charged` is what came out of your credits (`0` within the allowance).

### On Clonvo credits

When none of your keys can serve a call, Clonvo sends it to treg on Clonvo’s own treg account. treg tries its providers for the tool, cheapest first, and moves on when one fails or finds nothing. Some of those providers are free; most charge a fraction of a cent per call, and company and people data providers often charge per result returned.

-   `usage.cost` is the call’s cost in USD: treg’s price, or the provider’s list price when treg reports no charge for a call that succeeded. A call can also pay for providers that found nothing before the one that answered.
-   `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 and sends treg the lower cap, so the call can’t cost more than that. Most calls cost far less than the full cap and still go through. If none of treg’s providers can serve the call 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 pays only for providers that 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

treg doesn’t run research or browser agents, so without your own key `web_research` and `browser_task` run on Clonvo’s own provider keys: Parallel, then Exa, for research, and TinyFish for browser tasks. 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 that’s the provider’s price for the `depth`: Parallel $0.01 standard and $0.025 deep, Exa $0.025 and $0.10. For a browser task it’s `max_steps` at $0.016 a step (30 steps by default, $0.49 with the margin).
-   When the job ends, `usage.cost` is what the provider billed 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 any provider runs. Lower `max_steps` or choose standard `depth` to need less.
-   A cancelled or timed-out job is charged what the provider still bills for it: the steps a browser task took, Exa’s usage so far, or the full price of a Parallel run, which can’t be stopped once started.

## Calling a tool over REST

Tools live under the same base URL as chat completions, `https://api.clonvo.com/v1`, and use the same `Authorization: Bearer` header.

| Endpoint | Description |
| --- | --- |
| `GET /v1/tools` | Every tool, with its description, JSON Schema and the providers your organization can use right now. |
| `POST /v1/tools/{id}` | Calls one tool. The body has `arguments` and an optional `provider` object. |

### List tools

```bash
curl https://api.clonvo.com/v1/tools \
  -H "Authorization: Bearer $CLONVO_API_KEY"
```

```json
{
  "data": [
    {
      "id": "web_search",
      "name": "Web search",
      "description": "Search the web and get a ranked list of pages…",
      "input_schema": {
        "type": "object",
        "properties": { "query": { "type": "string" } },
        "required": ["query"]
      },
      "providers": ["tavily", "exa", "tinyfish", "parallel", "firecrawl", "treg"],
      "available_providers": ["tavily", "treg"]
    }
  ]
}
```

`input_schema` is shortened here. `available_providers` lists the providers you have an enabled key for, plus `treg` when your organization can pay with credits (a paid plan and a balance above zero). A tool with an empty list can’t be called yet.

### Search the web

#### curl

```bash
curl https://api.clonvo.com/v1/tools/web_search \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": { "query": "PostgreSQL 18 release notes", "max_results": 3 }
  }'
```

#### Python

```python
import os
import requests

resp = requests.post(
    "https://api.clonvo.com/v1/tools/web_search",
    headers={"Authorization": f"Bearer {os.environ['CLONVO_API_KEY']}"},
    json={"arguments": {"query": "PostgreSQL 18 release notes", "max_results": 3}},
    timeout=60,
)
resp.raise_for_status()
for hit in resp.json()["result"]["results"]:
    print(hit["title"], hit["url"])
```

#### Node.js

```js
const resp = await fetch("https://api.clonvo.com/v1/tools/web_search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLONVO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ arguments: { query: "PostgreSQL 18 release notes", max_results: 3 } }),
});
if (!resp.ok) throw new Error((await resp.json()).error.message);
const { result } = await resp.json();
for (const hit of result.results) console.log(hit.title, hit.url);
```

#### Response

```json
{
  "id": "gen-01M69T8V4J2QH3K5N7P9R1S3TX",
  "tool": "web_search",
  "provider": "tavily",
  "result": {
    "query": "PostgreSQL 18 release notes",
    "results": [
      {
        "title": "PostgreSQL 18 Release Notes",
        "url": "https://www.postgresql.org/docs/18/release-18.html",
        "snippet": "Release date: 2025-09-25. This release contains a variety of fixes…",
        "published_at": null,
        "score": 0.86
      }
    ]
  },
  "usage": { "cost": 0.008, "charged": 0, "is_byok": true }
}
```

| Field | Description |
| --- | --- |
| `id` | The call’s generation id, also sent in the `x-clonvo-generation-id` header (errors included). It appears in **Activity** and works with [`GET /v1/generation`](https://clonvo.com/docs/other-endpoints.md#get-v1-generation). |
| `tool`, `provider` | The tool you called and the provider that served it: one of your own-key providers, or `treg` for a call on Clonvo credits. |
| `served_by` | Only with `provider: "treg"`: the provider treg routed the call to, such as `exa` or `serper`, when treg names it. |
| `result.results[]` | `title`, `url` and `snippet` for each page. `snippet` is a short excerpt on one line, at most 500 characters, cut at a word with “…”. With `include_content`, `content` has the page text, up to `max_content_chars`. `published_at` and `score` are set when the provider returns them. |
| `result.notes` | Present when a provider handled an argument differently (see [Where providers differ](#where-providers-differ)). |
| `usage` | `charged` is what Clonvo deducted from credits. On your own key, `cost` is the list price and `is_byok` is `true`. On Clonvo credits, `cost` is the call’s cost (see [Billing](#billing)) and `is_byok` is `false`. |

### Read a page

```bash
curl https://api.clonvo.com/v1/tools/web_scrape \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "url": "https://www.postgresql.org/about/" } }'
```

```json
{
  "id": "gen-01M69T9C2B6D8F0H2K4M6P8R0T",
  "tool": "web_scrape",
  "provider": "firecrawl",
  "result": {
    "url": "https://www.postgresql.org/about/",
    "title": "PostgreSQL: About",
    "content": "# About\n\nPostgreSQL is a powerful, open source…",
    "format": "markdown",
    "truncated": false,
    "status_code": 200,
    "published_at": null
  },
  "usage": { "cost": 0.0038, "charged": 0, "is_byok": true }
}
```

`truncated` is `true` when the page was longer than `max_chars` and was cut. `status_code` is the HTTP status the provider got from the page, when it reports one.

### Get an answer with sources

```bash
curl https://api.clonvo.com/v1/tools/web_answer \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "query": "Who founded Weaviate and when?" } }'
```

```json
{
  "id": "gen-01M6A2D3E4F5G6H7J8K9M0N1P2",
  "tool": "web_answer",
  "provider": "treg",
  "served_by": "exa",
  "result": {
    "query": "Who founded Weaviate and when?",
    "answer": "Weaviate was founded in 2019 by Bob van Luijt and Etienne Dilocker in Amsterdam.",
    "citations": [
      { "title": "SeMI Technologies becomes Weaviate", "url": "https://www.prnewswire.com/news-releases/semi-technologies-becomes-weaviate-301724760.html", "published_at": "2023-01-18T14:00:00.000Z" }
    ]
  },
  "usage": { "cost": 0.005, "charged": 0.0051, "is_byok": false }
}
```

### Look up a company

```bash
curl https://api.clonvo.com/v1/tools/company_enrich \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "domain": "weaviate.io" } }'
```

```json
{
  "id": "gen-01M6A2F7H9K1M3P5R7T9V1X3Z5",
  "tool": "company_enrich",
  "provider": "treg",
  "served_by": "branddev",
  "result": {
    "company": {
      "name": "Weaviate",
      "domain": "weaviate.io",
      "website": "https://weaviate.io",
      "description": "Weaviate is an open-source, deployment-agnostic vector database platform…",
      "industry": null,
      "employees": "73",
      "location": "Amsterdam Netherlands",
      "founded": null,
      "linkedin_url": null
    }
  },
  "usage": { "cost": 0.0005, "charged": 0.00051, "is_byok": false }
}
```

When no provider knows the company, `company` is `null` and `notes` says so.

### With a model’s tool calling

`input_schema` is a valid function `parameters` object, so you can offer the tools to any model through [tool calling](https://clonvo.com/docs/tool-calling.md) and run the calls your model makes through `POST /v1/tools/{id}`. If your framework speaks MCP, connecting to the [MCP server](https://clonvo.com/docs/mcp.md) does this for you.

## Long-running tools

`web_crawl`, `web_research` and `browser_task` run as jobs. `POST /v1/tools/{id}` answers with a job instead of the usual response: `202` while the provider is still working, or `200` when the job finished within the request (Tavily’s crawl, and crawls on Clonvo credits, do). The job’s `id` is the call’s generation id.

```bash
curl https://api.clonvo.com/v1/tools/web_research \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "query": "Which open source vector databases support hybrid search?" } }'
```

```json
{
  "id": "gen-01M6B4Q8R2T4V6X8Z0B2D4F6H8",
  "object": "tool.job",
  "tool": "web_research",
  "status": "running",
  "provider": "exa",
  "created_at": "2026-11-09T12:00:00.000Z",
  "completed_at": null,
  "poll_after_ms": 10000
}
```

Check it with `GET /v1/tools/jobs/{id}`, waiting about `poll_after_ms` between checks. Once `status` is `completed`, `result` holds the tool’s result and `usage` what it cost; `failed` and `cancelled` jobs carry `error` instead. `DELETE /v1/tools/jobs/{id}` cancels a running job: Clonvo asks the provider to stop where it can (Firecrawl, Exa and TinyFish can; Parallel can’t, so its run may still finish and bill your Parallel account). On Clonvo credits, a cancelled job is charged what the provider still bills for it (see [Research and browser tasks on credits](#research-and-browser-tasks-on-credits)).

| Endpoint | Description |
| --- | --- |
| `GET /v1/tools/jobs/{id}` | The job: its status, and its result or error once it’s final. |
| `DELETE /v1/tools/jobs/{id}` | Cancels a running job. A final job is returned unchanged. |

-   Clonvo checks the provider in the background as well, so a job finishes and is billed even if you never ask for it again.
-   A job is billed once, when it ends, like any tool call: on your own key, its list price counts toward your BYOK allowance and the fee applies above it; on Clonvo credits, it’s charged what the provider billed plus 2%. Clonvo holds credits for the most it can be charged from the start, until the job ends.
-   A job stops after 30 minutes (45 for `web_research`) and fails with `job_timeout`.
-   Jobs are kept for 24 hours after they finish; after that `GET` answers `404` with `tool_job_not_found`.
-   Over MCP, clients that support tasks get one for each job; other clients get the job’s id and the `job_status` tool. See [MCP](https://clonvo.com/docs/mcp.md#long-running-tools).

## Routing between providers

Without a `provider` object, Clonvo tries the providers you have a key for in the tool’s default order (see [Available tools](#available-tools)), then treg on Clonvo credits. Add one to change that for a call:

| Field | Description |
| --- | --- |
| `order` | Try these providers first, in this order. Providers you leave out come after them in the default order. |
| `only` | Use only these providers. |
| `ignore` | Never use these providers. |
| `allow_fallbacks` | Try the next provider when one fails with an error worth retrying. Default `true`. With `false`, Clonvo uses only the first provider in the list (trying each of your keys for it); if that’s an own-key provider you have no key for, the call fails. |

```json
{
  "arguments": { "url": "https://example.com/pricing" },
  "provider": { "order": ["exa", "firecrawl"], "allow_fallbacks": false }
}
```

`treg` works in `order`, `only` and `ignore` like any other provider: `{"order": ["treg"]}` tries Clonvo credits first, and `{"ignore": ["treg"]}` keeps calls on your own keys. Own-key providers take part only with an enabled key, and treg only when your balance is above zero. 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). Unknown provider ids in `order`, `only` or `ignore` fail the call with `400`.

Turn on **Always use this key** for a tool key and, when that key fails, Clonvo returns the error instead of moving on to another provider.

### When Clonvo moves on

| What happened | Falls back? |
| --- | --- |
| The provider rejected the key (`401`, `403`) | Yes, to your next key, then the next provider. The error is shown on the key under **Provider keys**. |
| The provider account is out of credits or over its plan limit | Yes |
| Rate limit, timeout, server error, or the provider couldn’t read the page | Yes |
| The provider rejected the request itself (another `4xx`) | No. The error is returned straight away. |
| treg is unavailable, busy, or none of its providers could answer | Yes, to your next provider if treg wasn’t last. |

If every provider fails, you get the error from the last one. Only the call that succeeded counts toward your allowance or is charged to credits; failed attempts cost nothing on Clonvo.

## Errors

Tool errors use the [usual error shape](https://clonvo.com/docs/errors.md). These codes are specific to tools:

| Status | Code | When, and what to do |
| --- | --- | --- |
| `404` | `tool_not_found` | The tool id in the URL doesn’t exist. Use an id from `GET /v1/tools`. |
| `400` | `invalid_tool_arguments` | `arguments` doesn’t match the tool’s schema: a missing or unknown argument, or a value out of range. `param` names the argument, for example `arguments.max_results`. |
| `400` | `tool_requires_own_key` | No enabled key for any provider that can serve the tool, after your `provider` settings, and the call can’t run on Clonvo credits because your settings exclude `treg` or credits aren’t offered. Add a key under **Provider keys**, or loosen `only` and `ignore`. |
| `400` | `no_allowed_providers` | Your `provider` settings exclude every provider that serves the tool. |
| `402` | `byok_requires_paid_plan`, `insufficient_credits` | Your organization is on Free. Buy credits to move to Pay as you go. |
| `402` | `byok_fee_requires_credits`, `insufficient_credits`, `key_limit_exceeded` | There aren’t enough credits for the call on Clonvo credits even at its lowest cap, or treg couldn’t serve it within the lower cap your credits allow, or there aren’t enough for the BYOK fee past the monthly allowance, or the API key’s spending limit can’t cover it. The message says which. |
| `503` | `tools_unavailable` | Web tools on Clonvo credits are temporarily unavailable. Try again in a few minutes, or add your own key. A tool that runs only on Clonvo credits (`company_enrich`, `company_news`, `company_jobs`, `people_enrich`) has no key to fall back to. |
| `429` | `tool_spend_limit_reached` | Your organization reached the spending limit Clonvo set for web tools on credits. Try again later, or add your own key. |
| `403` | `tools_blocked` | Web tools on Clonvo credits are turned off for your organization. Contact support, or add your own key. |
| `404` | `tool_job_not_found` | No job with that id for your organization, or it finished more than 24 hours ago. |
| `502` | `route_failed`, `tool_price_limit` | None of treg’s providers could answer, or none could within Clonvo’s price cap for the call. Try again shortly. |

Errors from a provider start with its name, for example `Tavily is rate-limiting this key (429).`, and keep the provider’s status where it’s meaningful. On Clonvo credits they name the provider treg routed to, for example `serper (via treg) returned an error (503).`

## In your activity

Every tool call is recorded like a model request. In **Activity**, tool calls carry a **Tool** tag and show the tool name, the provider, cost and latency; token and speed columns stay empty. Calls on Clonvo credits show `treg` as the provider and **Credits** as the billing, and their details name the provider treg routed the call to. With [content retention](https://clonvo.com/docs/privacy.md) on, the call’s arguments and result are stored and shown in its details.

## Your queries and Clonvo

By default, Clonvo stores the inputs of each successful web tool call (the search query or URL, its options, the tool, the provider and the time) to train and improve its search. Free text you write for a tool (a `web_answer` question, a `web_extract` prompt or schema, `web_crawl` instructions, a `web_research` brief, a `browser_task` goal) is never stored for this, nor are company and people lookups, including `web_search` with category `people` or `company`. It never stores the results or page content for this, or which key, project or user made the call. An owner or admin can turn this off with **Improve Clonvo with your web searches** under **Settings → Privacy**; it applies to calls on your own keys and on Clonvo credits alike. Don’t put personal or confidential information, or access tokens, in queries and URLs. See [Web tool queries](https://clonvo.com/docs/privacy.md#web-tool-queries).