On this page
Web search
POST /v1/tools/search searches the web and returns the results, so a client can give its model fresh sources without a hosted tool. It takes the same key and the same admission as the inference endpoints, and every answered query is billed at the platform search price. While the platform runs its own search engine that price is zero, so a search costs nothing.
Request#
| Field | Type | Notes |
|---|---|---|
queries | array of strings | Required. One to four queries, the body at most 16 KiB. A query longer than 400 bytes is cut at a character boundary before it is sent or billed |
Response#
notice and untrusted mark everything in the answer as text this platform did not write. A result's title and snippet are the page's own words: pass them to your model as data, never as instructions, and tell it the same. The service also breaks the markers a page could use to look like a turn of the conversation (system:, <|im_start|>, [INST], <<SYS>>), so the text stays readable without acting as a control token.
Pass the answer on whole, notice and untrusted included. If the key has guard_injection on, the text is checked when it comes back as a tool result: warn reports the findings in x-token-notice, block refuses the next request with 400 injection_suspected. guard_credentials treats it like any other text in the request.
The search is configured by the platform: there is no region or retention setting to choose. The query is used to answer the call and is not kept; the request's usage record holds the model web_search, the price and the day, with no text.
Each answered query contributes up to five results, title, url and snippet, with every URL once. A query that failed is left out of the answer and of the bill. If every query failed, or search is off, the answer is a 503 and nothing is charged.
| Header | Meaning |
|---|---|
x-request-id | The request id |
x-token-cost | What the answered queries cost, in EUR |
retry-after | On a 429, when the daily cap frees |
Billing#
A search holds the price of all its queries first, then bills only the ones answered, from the balance. While the platform runs its own search engine the price is zero, so the hold is zero and the usage row appears with no charge. The charge appears in the usage rows as the model web_search, with its price and no tokens.
An account can run 200 queries a day by default, counted on the UTC day. A request whose queries would pass the cap is refused with a 429 until the day turns.
Is search on#
GET /v1/tools/search answers {"available": true} when a search sent now would work, and {"available": false} otherwise. It is never billed and counts against no limit, so a client can leave its web search tool out while search is off.
Errors keep the OpenAI shape. Errors lists the classes.