Web search in chat

Add web_search to any chat request and we run the search before the model does, then hand it the results as numbered, linked context. You get back a normal chat completion plus a web_search object listing the exact pages the answer was built from.

This works with every model in the catalog, including ones with no native tool calling — the results arrive as context, so there is nothing for the model to support.

curl https://api.xkiro.com/v1/chat/completions \
  -H "Authorization: Bearer $XKIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "web_search": { "enable": true, "count": 5 },
    "messages": [
      { "role": "user", "content": "What shipped in the latest Node.js LTS? Cite your sources." }
    ]
  }'

Two ways to turn it on#

Both forms are equivalent. Use whichever your existing code already speaks — if you are moving an integration across, you should only have to change the base URL.

{
  "model": "openai/gpt-5.5",
  "web_search": { "enable": true, "count": 5 },
  "messages": [ … ]
}

{
  "model": "openai/gpt-5.5",
  "tools": [
    { "type": "web_search", "web_search": { "count": 5 } }
  ],
  "messages": [ … ]
}

Options#

Response#

The completion is unchanged — same shape your SDK already parses. We add one extra top-level field.

{
  "id": "chatcmpl-130dde45-…",
  "object": "chat.completion",
  "choices": [ { "message": { "content": "Node.js 26 LTS shipped … [1][2]" } } ],
  "usage": { "prompt_tokens": 2607, "completion_tokens": 154 },
  "web_search": {
    "status": "ok",
    "results": [
      {
        "title": "Node.js 26 is now LTS",
        "url": "https://nodejs.org/en/blog/release/v26.0.0",
        "snippet": "Node.js 26 has been promoted to Long Term Support…",
        "source": "nodejs.org",
        "faviconUrl": "https://…/favicon.png"
      }
    ],
    "remaining_today": 19,
    "notice": null
  }
}

When search is unavailable, you still get an answer#

If your allowance is used up, you hit a rate limit, or search is briefly down, we do not fail the request. You asked a question and switched a feature on; the feature being unavailable is not a reason to throw the question away. The model answers anyway — and it is told, in the prompt, to say plainly that it could not search and to invent nothing.

{
  "choices": [
    {
      "message": {
        "content": "I could not search the web this time.\n\nThe capital of France is Paris. As of my last knowledge update…"
      }
    }
  ],
  "web_search": {
    "status": "quota_exhausted",
    "results": [],
    "remaining_today": null,
    "notice": "Daily web search allowance used up — answered without live results. It frees up as the rolling 24-hour window moves, or upgrade your plan for more."
  }
}

Allowances and pricing#

A chat request with search on costs exactly one search, no matter how long the answer is — we run the search once, up front, rather than letting the model decide how many times to call a tool. It draws from the same daily allowance as the standalone endpoint.

• The search and the completion are billed separately: one search against your web allowance, plus the usual tokens for the model.
• Results add to your prompt tokens — roughly 2,000–3,000 for ten results. Lower count if that matters more to you than breadth.
• A search that did not run is never billed, and never counts against the allowance.

Practical notes

• We search the last user message, as written. Long preambles make weak queries — if you control the prompt, put the searchable question last.
• Ask for citations in your own prompt too. The model is already instructed to cite [1], [2], but saying so again reliably improves how consistently it does.
• Need the full text of a page rather than a snippet? Call web fetch with the URL you got back.
• Want the raw results without a model in the loop — to rank or cache them yourself? Use POST /v1/search.