> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web search

> Let the model search the web for up-to-date information and cite its sources.

Early access
**Gnani Evon v3.5** is now available as an API to early access registrants.

The model's knowledge stops at its training date. With web search, it can look things up (today's weather, current prices, recent events) and answer with sources.

## When to use this

* **Questions about now**, such as the weather this weekend or today's prices.
* **Recent events** that happened after the model was trained.
* **Answers you want to cite**, with links your users can check.

```bash cURL highlight={7} theme={null}
curl https://api.vachana.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: $GNANI_API_KEY" \
  -d '{
    "model": "evon-v3.5",
    "messages": [{"role": "user", "content": "Will it rain in Mumbai this weekend?"}],
    "tools": [{"type": "web_search"}]
  }'
```

```python Python (OpenAI SDK) highlight={12} theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.vachana.ai/v1",
    api_key=os.environ["GNANI_API_KEY"],
)

completion = client.chat.completions.create(
    model="evon-v3.5",
    messages=[{"role": "user", "content": "Will it rain in Mumbai this weekend?"}],
    tools=[{"type": "web_search"}],
)

message = completion.choices[0].message
print(message.content)
print(getattr(message, "web_search", None))   # queries and sources
```

```javascript JavaScript (OpenAI SDK) highlight={11} theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.vachana.ai/v1",
  apiKey: process.env.GNANI_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "evon-v3.5",
  messages: [{ role: "user", content: "Will it rain in Mumbai this weekend?" }],
  tools: [{ type: "web_search" }],
});

const message = completion.choices[0].message;
console.log(message.content);
console.log(message.web_search);   // queries and sources
```

```python Python (requests) highlight={10} theme={null}
import os
import requests

response = requests.post(
    "https://api.vachana.ai/v1/chat/completions",
    headers={"X-API-Key-ID": os.environ["GNANI_API_KEY"]},
    json={
        "model": "evon-v3.5",
        "messages": [{"role": "user", "content": "Will it rain in Mumbai this weekend?"}],
        "tools": [{"type": "web_search"}],
    },
    timeout=120,
)
response.raise_for_status()
message = response.json()["choices"][0]["message"]
print(message["content"])
print(message.get("web_search"))   # queries and sources
```

```json Response expandable wrap theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Light rain is likely in Mumbai on Saturday, with a drier Sunday [1]. Carry an umbrella if you are out on Saturday afternoon [2].",
        "web_search": {
          "queries": ["Mumbai weather forecast this weekend"],
          "sources": [
            {
              "id": 1,
              "title": "Mumbai weekend forecast",
              "url": "https://example.com/mumbai-forecast",
              "snippet": "Saturday: light showers in the afternoon. Sunday: partly cloudy..."
            },
            {
              "id": 2,
              "title": "Monsoon update for the Konkan coast",
              "url": "https://example.org/konkan-update",
              "snippet": "Isolated showers are expected along the coast on Saturday..."
            }
          ],
          "remaining_today": 9
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 1630, "completion_tokens": 112, "total_tokens": 1742}
}
```

## Turn on web search

Add the built-in `web_search` tool to `tools`. **The service runs the searches for you.** Unlike [function tools](https://docs.gnani.ai/api/LLM/tool-calling.md), you do not run anything or send results back. You get the final answer, with numbered citations like `[1]` and the list of sources.

```json highlight={4} theme={null}
{
  "model": "evon-v3.5",
  "messages": [{"role": "user", "content": "Will it rain in Mumbai this weekend?"}],
  "tools": [{"type": "web_search"}]
}
```

The model decides whether a search is needed. For a question it can answer on its own, it may not search at all.

***

## Response

When the model searched, `message.web_search` lists what it searched for and the sources it was given. The answer cites them by `id`. The full response is in the example panel.

| Field | Meaning |
| - | - |
| `queries` | The searches the model ran, in order. |
| `sources` | Every result the model was given. `id` is the number it cites as `[id]`; numbering runs across all searches in the request. `snippet` is the relevant text from the page. |
| `remaining_today` | How many searches you have left today. |

`usage` adds up every model call made for the request, including the search results the model read. A searched answer therefore uses more tokens than a plain one.

> [!NOTE]
>
> OpenAI returns citations as `annotations` of type `url_citation`. Here they come as `[n]` markers in `content` and the list in `message.web_search.sources`.

### Showing citations

To show citations, replace each `[n]` in `content` with a link to `sources[n-1].url`, or list the sources under the answer. These helpers look each source up by its `id` and turn the markers into Markdown links:

```python Python (OpenAI SDK) highlight={5,11} theme={null}
import re

def link_citations(message: dict) -> str:
    """Turn each [n] in the answer into a Markdown link to source n."""
    sources = {s["id"]: s for s in (message.get("web_search") or {}).get("sources", [])}

    def to_link(match):
        source = sources.get(int(match.group(1)))
        return f"[{match.group(0)}]({source['url']})" if source else match.group(0)

    return re.sub(r"\[(\d+)\]", to_link, message.get("content") or "")

print(link_citations(completion.choices[0].message.model_dump()))
# Light rain is likely ... drier Sunday [[1]](https://example.com/mumbai-forecast). ...
```

```javascript JavaScript (OpenAI SDK) highlight={3-4} theme={null}
// Turn each [n] in the answer into a Markdown link to source n.
function linkCitations(message) {
  const sources = new Map((message.web_search?.sources ?? []).map((s) => [s.id, s]));
  return (message.content ?? "").replace(/\[(\d+)\]/g, (marker, n) => {
    const source = sources.get(Number(n));
    return source ? `[${marker}](${source.url})` : marker;
  });
}

console.log(linkCitations(completion.choices[0].message));
// Light rain is likely ... drier Sunday [[1]](https://example.com/mumbai-forecast). ...
```

***

## Streaming

With `"stream": true`, you see each search as it happens. A chunk whose `choices[0].delta.web_search` is set reports progress; the answer then streams in `delta.content` as usual.

```text wrap theme={null}
data: {..."choices":[{"index":0,"delta":{"web_search":{"status":"searching","query":"Mumbai weather forecast this weekend"}}}]}

data: {..."choices":[{"index":0,"delta":{"web_search":{"status":"completed","query":"Mumbai weather forecast this weekend","sources":[{"id":1,"title":"Mumbai weekend forecast","url":"https://example.com/mumbai-forecast","snippet":"..."}],"remaining":9}}}]}

data: {..."choices":[{"index":0,"delta":{"content":"Light rain is likely in Mumbai on Saturday [1]"}}]}
```

> [accordion] Search status values
>
> | `status` | Meaning |
> | - | - |
> | `searching` | A search has started. `query` is what is being searched. |
> | `completed` | The search finished. `sources` holds the results (empty if nothing was found), and `remaining` the searches left today. |
> | `failed` | The search could not run. The model answers without it. |
> | `limit_reached` | Your daily search limit was reached during this request. The model answers without searching further. |

> [!NOTE]
>
> A failed search never fails the request. The model answers from what it knows and says that live search was not available.

***

## Limits

| Limit | Value |
| - | - |
| Searches per day | **10 per user**, reset at midnight IST |
| Search rounds per request | Up to 3. The model can run several searches in one round. |

> [!WARNING]
>
> When the day's searches are already used up, a request with the `web_search` tool is refused with `429 web_search_limit_exceeded`. `Retry-After` gives the seconds until midnight IST. To answer anyway, send the request without the tool.

Tokens used for a searched answer count toward your [daily token quota](https://docs.gnani.ai/api/LLM/limits.md) like any other request.

***

## Rules

* `tool_choice` must be `auto` (the default) or `none`. `none` turns search off for the request.
* You can send your own function tools in the same request. If the model calls one of them, the reply is returned to you with `tool_calls`, as in [Tool calling](https://docs.gnani.ai/api/LLM/tool-calling.md).
* Do not name one of your own functions `web_search` or `search`; the request is refused with `400`.
* If web search is not available, the request is refused with `503 web_search_unavailable`. Retry later, or send it without the tool.
* Search results are screened by the [safety filters](https://docs.gnani.ai/api/LLM/safety.md) like any other text. A result that fails the check is dropped, and the model answers without it.

***

## Related

> [card] [Tool calling](https://docs.gnani.ai/api/LLM/tool-calling.md)
>
> Use web search alongside your own functions.

> [card] [Limits](https://docs.gnani.ai/api/LLM/limits.md)
>
> Daily searches and the daily token quota.

> [card] [Streaming](https://docs.gnani.ai/api/LLM/streaming.md)
>
> Read search progress and the answer as they arrive.

> [card] [Safety and privacy](https://docs.gnani.ai/api/LLM/safety.md)
>
> How search results are screened.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.