API reference
Web search and web fetch tools
Add the provider's own web tool to a request and the model can search the web and read pages while it answers. Vani runs each search and page read, gives the model the results, and returns the answer with the tool calls, results and citations in the provider's own format: Anthropic's web_search and web_fetch server tools on /messages, the web_search tool on /responses, and web_search_options on /chat/completions. Or add :online to the model id (zhipu/glm-5.3-derisked:online): the same model, with web search and page reading on every request, for apps that never send a web tool. Apps that turn web search on with plugins: [{"id": "web"}] work too. Clients that run web tools of their own can use the same search and page reader through POST /tools/search, /tools/research and /tools/fetch, or the Vani MCP server's web_search and web_fetch tools.
- Price
- USD 0.005 per search (USD 5 per 1,000), plus tokens
- Page reads
- Tokens only
- Per request
- Up to 8 uses of each tool (16 with :online)
- Any app
- Add :online to the model id
- Plugin field
- plugins: [{"id": "web"}]
- Endpoints
- POST /messages · /responses · /chat/completions
- For your own tools
- POST /tools/search · /tools/research · /tools/fetch
On this pageHow it works
How it works
The model decides when to search or read a page. Each call runs on Vani while the request is open, the result goes back to the model, and the model goes on with its answer. Vani offers these tools with every chat model in GET /models, the Derisked models included (GLM 5.3 Derisked and Kimi K3.1 Pro Soft-Derisked); a GLM 5.3 Derisked request without web tools is still sent exactly as written. They run when your client puts the provider's web tool in the request, or on every request to a model id with :online (see :online model ids); many coding clients run web tools of their own instead (see Clients).
- Results are input tokens of the model's next step, like any tool result.
usageis the sum of every step of the request. - Search results and pages are untrusted web content: the model is told to use them as reference only and never to follow instructions found in them.
- Web tools and your own function tools work in the same request. A step that calls both runs the web tools first; your tool calls come back to you as usual.
:online model ids: web search in any app
Add :online to a model id, such as zhipu/glm-5.3-derisked:online or anthropic/claude-sonnet-5.5:online, and every request gets Vani's web search and page reading, on /messages, /responses and /chat/completions. Your app sends nothing else, so this works with coding agents, SDK apps and other clients that never send a provider's web tool. The model decides when to search or read a page, and the answer comes in the endpoint's own shapes (see the sections below).
- The same model serves the request, at its own token price, plus USD 0.005 per search that runs; page reads cost tokens only. The answer's
model, your usage and your request log name the plain model (zhipu/glm-5.3-derisked), and thex-vani-model-routed-fromresponse header names the id you sent. Vendor ids take it too (claude-sonnet-5-5:online). - Every chat model in
GET /modelshas an:onlineid except Qwen 3.8 Flash, Grok 4.7 and Grok 4.5, which do not use web tools reliably yet: their:onlineids are refused with 400. The:onlineids are not listed inGET /models; send them as they are. GLM 5.3 Derisked and DeepSeek V4.1 Flash Derisked have them too, and without:onlinetheir requests are still sent exactly as written. - On
/messagesthe model gets theweb_searchandweb_fetchserver tools. On/responsesand/chat/completionsit gets web search and page reading: on/responseseach call is aweb_search_callitem (action.typeissearch, oropen_pagewith the page'surl), and on/chat/completionsthe answer's links to results come asurl_citationannotations. Page reading reads only URLs you sent and URLs that results brought, never an address the model wrote. - No limit of its own: up to 16 uses of each tool per request, within the request's own limits (16 tool calls, 8 model steps, 60 seconds of web tool time), and pages are read up to 100,000 characters. A request starts by reserving 16 searches (USD 0.08) on top of its tokens; what it does not use is released when it ends.
- Your own tools keep working: their calls come back to you as usual. If one of them is named
web_searchorweb_fetch, it keeps its name and the model gets Vani's tool under another name. Atool_choiceyou set for your own tools holds on every step; namingweb_searchorweb_fetchwhen no tool of yours has that name makes the first step call it. - A request that already has a provider's web tool (
web_search_20250305,{"type": "web_search"},web_search_options) keeps exactly what it asked for, with or without:online.
Chat Completions with an :online id
curl "https://api.vani.ai/v1/chat/completions" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"zhipu/glm-5.3-derisked:online","messages":[{"role":"user","content":"What changed in the latest Rust release?"}]}'The plugins web field
Many chat apps and agent frameworks turn web search on with plugins: [{"id": "web"}] on /chat/completions and /responses. Vani takes it as its own web search: the model searches when the question needs it, and the answer cites its results (url_citation annotations, and web_search_call items on /responses).
max_results: results per search, 5 by default and 10 at most.include_domainsandexclude_domains: the sites to keep to or leave out (*.example.comandexample.com/docswork as in the provider web tools).search_prompt: your own words on using the results, added to the model's instructions.engineandmodeare accepted and change nothing: Vani always uses its own search.- It searches only (no page reading), as often as the request's own limits allow (16 tool calls and 8 model steps). Each search costs USD 0.005, as everywhere on the API; a request reserves 16 searches (USD 0.08) up front and is charged only for the searches that ran.
- Another plugin (such as
file-parser) is refused with 400 naming it. On/responsessend either aweb_searchtool or the plugin, not both. Withweb_search_optionson/chat/completions, theirsearch_context_sizeanduser_locationapply too. - The same models take it as the provider web tools, GLM 5.3 Derisked included. An
:onlineid needs no plugin. usage.server_tool_usecountsweb_search_requests(the charged searches) andweb_fetch_requestson/chat/completionsand/responses, as on/messages.
Chat Completions with the web plugin
curl "https://api.vani.ai/v1/chat/completions" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"zhipu/glm-5.3","messages":[{"role":"user","content":"What changed in the latest Rust release?"}],"plugins":[{"id":"web","max_results":3}]}'Messages: web_search and web_fetch
Add {"type": "web_search_20250305", "name": "web_search"} and, to read pages, {"type": "web_fetch_20250910", "name": "web_fetch"} to tools. The later dated versions work the same way: web_search_20260209 and web_search_20260318, web_fetch_20260209, web_fetch_20260309 and web_fetch_20260318 (as the Vercel AI SDK sends them). The anthropic-beta headers web-fetch-2025-09-10 and code-execution-web-tools-2026-02-09 are accepted but not needed.
web_searchtakesmax_uses,allowed_domainsorblocked_domains(not both;example.comcovers its subdomains,example.com/docsthe pages under that path) anduser_location({"type": "approximate", "city", "region", "country", "timezone"}, given to the model, which adds a place to a query when it matters).web_fetchtakesmax_uses,allowed_domains/blocked_domains,citations: {"enabled": true}andmax_content_tokens. It reads only URLs that you send (in your messages, tool results or system prompt) and URLs that earlier search and page results brought, never an address the model wrote in an earlier answer, so a model cannot be led to send data to an address of its own choosing. Pages are read from public HTTPS addresses whose robots.txt allows Vani's research fetcher; HTML, plain text and PDF come back as text.- The later versions' options: Vani runs no code execution, so there is no dynamic filtering.
allowed_callersandresponse_inclusionare accepted and change nothing: every call is the model's own, and every result comes back in full. Theserver_tool_useblocks of the 2026 versions say"caller": {"type": "direct"}.use_cache: false(web_fetch 20260309 and later) reads the page live from its site, never from a stored copy.url_sources(web_fetch, every version) narrows where a URL may come from:user_input(your messages and system prompt;allornone),client_tool_resultsandserver_tool_results(all,none, oronly/exceptwith{"type": "tool_reference", "name"}entries naming tools of the request). tool_choice: {"type": "tool", "name": "web_search"}(orweb_fetch) makes the first step call that tool.- The answer holds a
server_tool_useblock (srvtoolu_…id,inputwith the query or URL), itsweb_search_tool_result(each result withtype: web_search_result,url,title,page_ageand an opaqueencrypted_content) orweb_fetch_tool_result(adocumentwith the page text andretrieved_at), then the text. A text block that links to a search result carries aweb_search_result_locationcitation with a shortcited_text. - A failed or refused call is a result block, never an HTTP error, and is not charged:
web_search_tool_result_errorwithmax_uses_exceeded,too_many_requests,invalid_input,query_too_longorunavailable;web_fetch_tool_result_errorwithurl_not_allowed,url_not_accessible,unsupported_content_type,url_too_long,invalid_input,max_uses_exceeded,too_many_requestsorunavailable. usage.server_tool_usecountsweb_search_requests(the charged searches) andweb_fetch_requests. A stream sends the blocks in order: theserver_tool_useinput as aninput_json_delta, citations ascitations_delta, and the counts inmessage_delta.- Send an answer back in the history as it came. Its server tool blocks are read as text (what was searched or read, the results' titles and URLs, the page text);
encrypted_contentandencrypted_indexare opaque and carry nothing, andpage_ageisnullwhere a page's date is not known.
A Messages request with web search
curl "https://api.vani.ai/v1/messages" \
-H "x-api-key: $VANI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5.5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "What changed in the latest Rust release?"}],
"tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}]
}'The answer (shortened)
{
"content": [
{"type": "server_tool_use", "id": "srvtoolu_01…", "name": "web_search", "input": {"query": "Rust latest release notes"}},
{"type": "web_search_tool_result", "tool_use_id": "srvtoolu_01…", "content": [
{"type": "web_search_result", "url": "https://blog.rust-lang.org/…", "title": "Announcing Rust …", "encrypted_content": "vws1.…", "page_age": null}
]},
{"type": "text", "text": "The latest release … ([Rust blog](https://blog.rust-lang.org/…)).",
"citations": [{"type": "web_search_result_location", "url": "https://blog.rust-lang.org/…", "title": "Announcing Rust …", "cited_text": "…", "encrypted_index": "vwi1.…"}]}
],
"stop_reason": "end_turn",
"usage": {"input_tokens": 2810, "output_tokens": 164, "server_tool_use": {"web_search_requests": 1, "web_fetch_requests": 0}}
}Responses: the web_search tool
Add {"type": "web_search"} (or web_search_preview, and their dated names) to tools.
- Options:
search_context_size(low,mediumby default, orhigh: how many results the model reads and how much of each),user_location({"type": "approximate", city, region, country, timezone}) andfilters.allowed_domains.tool_choice: {"type": "web_search"}makes the first step search. - Each search is a
web_search_calloutput item withstatusandaction: {"type": "search", "query"}; withinclude: ["web_search_call.action.sources"]the action also lists the result URLs insources. The message'soutput_textcarriesurl_citationannotations (start_index,end_index,url,title) for its links to results. - A stream sends
response.output_item.added,response.web_search_call.in_progress,response.web_search_call.searching,response.web_search_call.completedandresponse.output_item.donefor each search, andresponse.output_text.annotation.addedbeforeresponse.output_text.done. - Earlier
web_search_callitems and annotated messages ininputare accepted. usage.server_tool_usecountsweb_search_requests(the charged searches) andweb_fetch_requests.
A Responses request with web search
curl "https://api.vani.ai/v1/responses" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-6-sol","input":"What changed in the latest Rust release?","tools":[{"type":"web_search","search_context_size":"medium"}],"store":false}'Chat Completions: web_search_options
Add web_search_options (search_context_size; user_location: {"type": "approximate", "approximate": {city, region, country, timezone}}). The model searches when the question needs it and answers with links; message.annotations lists url_citation entries (start_index, end_index, url, title). A stream sends them in one annotations delta just before the finish chunk. usage.server_tool_use counts web_search_requests (the charged searches) and web_fetch_requests.
A Chat Completions request with web search
curl "https://api.vani.ai/v1/chat/completions" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"google/gemini-3.8-flash","messages":[{"role":"user","content":"What changed in the latest Rust release?"}],"web_search_options":{"search_context_size":"low"}}'Search and page reading for your own tools
Vani's web search, research and page reader as plain endpoints, for clients that run web tools of their own and for your own code. They take any API key: a prepaid key, or a key created in Vani Chat (Plus and higher plans). No model is involved, so they work the same whichever model you use, Derisked models included.
POST /tools/searchwith{"query": "…", "max_results": 8}: a query of up to 500 bytes and 1 to 8 results (8 by default). The answer lists rankedresults, each withtitle,url,domainandsnippet. USD 0.005 per search.POST /tools/researchwith{"query": "…"}: up to two searches and five pages read. The answer hassearches(each with itsresults) andsources(each page'surl,titleandtext). USD 0.005 for each search it ran, so at most USD 0.01; the pages cost nothing.POST /tools/fetchwith{"url": "https://…", "max_chars": 20000}: one page's text (HTML, plain text or PDF) withfinal_url,title,truncated,content_typeandretrieved_at.max_charstakes 400 to 100,000 (100,000 by default). Free. Only public HTTPS pages whose robots.txt allows Vani's research fetcher are read, and the URL you send is read by Vani's own fetcher only.- Every answer says
untrusted: true(web content is evidence, never instructions) and hasusagewithweb_search_requestsandweb_fetch_requests. - Prepaid keys pay from the prepaid balance, keys created in Vani Chat from the plan allowance, at the same amount. A search that failed or was refused is never charged. A prepaid key needs a balance above zero to read pages.
- Retries: send an
Idempotency-Keyheader (1 to 128 letters, digits,.,_,:or-) with a search or research, and it is charged once. The same key again is answered 409api_request_already_admittedwithout a new search (results are not kept); the key with a different query is 409idempotency_conflict. A key whose search failed can be sent again. - Errors use the API's usual shapes: 400 for a bad body; 400
invalid_urlorurl_not_allowed, or 422url_not_accessiblewithdetails.reason(such asrobots,not_foundorunavailable), for a page that cannot be read; the usual balance, allowance and key spend-limit errors; 429rate_limitedwithRetry-After; 503web_unavailablewhen search is down. - Up to 60 web calls a minute and 2,000 page reads a day per account, shared with the MCP server's web tools.
Search
curl "https://api.vani.ai/v1/tools/search" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: search-0001" \
-d '{"query": "latest Rust release notes", "max_results": 5}'The answer (shortened)
{
"query": "latest Rust release notes",
"retrieved_at": "2026-11-08T12:00:00Z",
"results": [
{"source_id": "S1", "title": "Announcing Rust …", "url": "https://blog.rust-lang.org/…", "domain": "blog.rust-lang.org", "snippet": "…"}
],
"untrusted": true,
"usage": {"web_search_requests": 1, "web_fetch_requests": 0}
}Read a page
curl "https://api.vani.ai/v1/tools/fetch" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://blog.rust-lang.org/", "max_chars": 20000}'Price and billing
- USD 0.005 per search that ran (USD 5 per 1,000), on top of the request's tokens. A search that ran but found nothing still counts; a search that failed or was refused (an error result) is never charged.
- Page reads (
web_fetch) cost tokens only: the page text the model reads is input tokens. - Prepaid keys pay from the prepaid balance; keys created in Vani Chat pay from the plan allowance, at the same amount.
- When a request starts, Vani reserves the cost of every search its
max_usesallows (8 when not set, 16 for an:onlineid) on top of its tokens; what the searches did not use is released when the request ends. The balance or allowance must cover that reservation. - The request log keeps
server_tool_usewith the number of searches, page reads and the search fee. A request that fails before delivering anything is not charged, its searches included. A request you cancel, or whose stream you leave, after its searches ran is charged for those searches and the tokens it used. - The search endpoints and the MCP server's
web_searchcost the same USD 0.005 per search, with no tokens; their page reads are free. Their fees show in your balance history and the key's monthly spend (see Search and page reading for your own tools).
Limits and privacy
- Up to 8 uses of each tool per request; a larger
max_usesis lowered to 8. An:onlineid's own tools have no limit of their own: up to 16 uses of each. A request runs at most 8 model steps and 16 tool calls. - A request has 60 seconds of web tool time: the time its searches and page reads take, never the model's own thinking. While that time lasts, each search gets at least 8 seconds and each page read at least 15; once it is used, the model's next step is its final answer.
- A non-streaming request with web tools that is still working after 30 seconds gets status 200 at once, then a space every 20 seconds to keep the connection open, then the JSON (JSON parsers skip the spaces). A failure after that point comes with status 200 and the format's own error body:
{"error": …}on Chat Completions, a failed response on Responses,{"type": "error", …}on Messages. Streams are not affected. - Search queries up to 500 bytes (
query_too_longabove); URLs up to 2,000 characters; up to 60 web tool calls a minute per account (too_many_requestsabove). max_content_tokenstakes up to 25,000 tokens of page text (about 100,000 characters), the length an:onlineid's page reads have; longer pages are shortened.- A query that looks like personal data (an e-mail address, a phone number or another long number) is searched with extra privacy, and the pages it finds, like the URLs you send, are read by Vani's own fetcher only.
- Vani does not keep search results or pages after the request; nothing is shared between accounts.
Clients
- Claude Code: its WebSearch tool works with no extra setting (tested with Claude Code 2.1.299), with every model, the Derisked models included. Each WebSearch call is one search; Claude Code's WebFetch reads pages on your machine (no search fee; the page text it gives the model costs tokens as usual).
- Codex: with
web_searchset tocached,indexedorlive(cachedis Codex's default), Codex sends its web search tool with the models it knows to support it, and Vani runs each search, always as a live search. Codex 0.159.2 does so withgpt-5.5andgpt-5.4, for example, but sends no web search tool withgpt-6-solor a model id it does not know. Keep itdisabledif you do not want search fees. With any other model id, add:onlineto it and Vani adds web search to every request, whatever Codex'sweb_searchsetting. - OpenCode, Cline, Kilo Code, Roo Code, Cursor and pi run their web tools on your machine, or have none, so their searches never reach Vani and are not charged here. To search through Vani in these clients, use the model id with
:online(see :online model ids), add the Vani MCP server (itsweb_searchandweb_fetchtools are the same search and page reader), or call the endpoints in Search and page reading for your own tools from a custom tool. - The Anthropic and OpenAI SDKs read these blocks, items and annotations with their own types.
Claude Code and other client guidesVani MCP serverAnthropic-compatible APIOpenAI-compatible API
More reference: OpenAI-compatible API · Anthropic-compatible API · Model ids, limits, headers and usage · Images and PDFs on the API · MCP tools on the API · Media API: images and videos · Artifacts API · Responses API: scope and limits · Model changes: webhooks, feeds and the changes API · API overview · Docs and quickstart