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.
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. 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.