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

# Web search

> Ground a chat completion in live web results.

The gateway plans the query, fetches sources, injects them as request-local context before the model call, and strips the tool from the upstream request. Nothing fetched is persisted. Available on models with `supports_web_search: true` (`GET /v1/models?supports=web_search`).

## Top-Level Field

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "z-ai/glm-5.2",
  "messages": [{ "role": "user", "content": "What shipped in the latest release?" }],
  "web_search": true
}
```

`true` requires search for the turn. `{"mode":"auto"}` lets the gateway skip retrieval when the conversation already answers the request.

## As a Tool

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "z-ai/glm-5.2",
  "messages": [{ "role": "user", "content": "..." }],
  "tools": [{ "type": "web_search", "parameters": { "allowed_domains": ["example.org"] } }]
}
```

`allowed_domains` and `blocked_domains` are flat lists; conflicting lists are rejected. An explicit tool declaration always searches.

## Response

When search ran, the completion carries a top-level `web_search` object with the sources, and `usage.server_tool_use` counts requests and results. Generated queries and retrieval settings are not exposed.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "web_search": { "used": true, "sources": [ { "id": 1, "title": "...", "url": "https://...", "domain": "..." } ] },
  "usage": { "server_tool_use": { "web_search_requests": 1, "web_search_results": 8 } }
}
```

## Privacy and Usage

Search runs at the model's privacy level; hosted search is unavailable on the final Encrypted request. See [Data retention and visibility](/privacy/data-retention-and-visibility). Search counts toward usage in addition to the model's tokens.

## Related

* [Web fetch](/api/api-reference/server-tools/web-fetch)
* [Tool errors](/api/api-reference/server-tools/tool-errors)
* [Web search feature guide](/api/features/server-side-tools/web-search)

## Standalone search

`POST /api/v1/web/search` retrieves content without running a chat model. Authenticate with an API key or an OAuth bearer with `cli:inference`; browser cookies alone are not accepted.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://app.trynito.ai/api/v1/web/search \
  -H "Authorization: Bearer $NITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"PostgreSQL release notes"}'
```

The body accepts only `query`; omit model IDs, messages, and privacy-level options. The query must be nonblank, at most 400 UTF-8 bytes and 50 whitespace-delimited words. Results contain retrieved excerpts, not full pages.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "PostgreSQL release notes",
  "results": [
    {
      "title": "PostgreSQL release notes",
      "url": "https://www.postgresql.org/docs/current/release.html",
      "content": "Release information and changes.",
      "last_updated": null
    }
  ]
}
```

`last_updated` is a provider-supplied modification date or `null`. Each call is billed independently, using the subscription allowance before prepaid balance, and respects spend caps and rate limits. Retrieved content is request-local. After a `502 provider_error` with an unknown provider outcome, do not retry automatically: retrieval may already have been billed.

See the [standalone endpoint](/api/api-reference/endpoints/web/search) for schemas and errors.


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