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

# Web search in Responses API

> Give models access to current web information via the Responses API with built-in web search across OpenAI, Anthropic, and Google.

**Use Cases**

* Answering questions about events beyond the model's training cutoff.
* Grounding responses in live data (pricing, availability, breaking news).
* Research assistants that need to cite verifiable, up-to-date sources.
* Customer support bots that look up current documentation or policies at query time.

***

## Overview

Use **`POST /responses`** on the AI Gateway with the same request shape as the [OpenAI Responses API](https://developers.openai.com/api/reference/responses/overview): `model`, `input`, and a `tools` array that includes a built-in web search entry. The **AI Gateway** forwards search to each provider’s native capability when the model supports it. See [Responses API](/docs/ai-gateway/features/responses-api.md) for an overview of the endpoint and when to choose it over Chat Completions.

There is no separate Perplexity or Parallel tool in the **AI Gateway**; the supported contract is **OpenAI-style** `web_search` / `web_search_preview` tools on `/responses`, mapped to Anthropic and Google where applicable.

> [!NOTE]
>
> Prefer models whose metadata indicates web search support. See [Supported Models](/docs/ai-gateway/supported-models.md) and the workspace model list.

### Other ways to search

Chat Completions reaches web search through a different, gateway-run contract: the [`orq:web_search` server tool](/docs/ai-gateway/features/server-tools/web-search), where the **AI Gateway** runs each search and returns the results to the model, configured with `max_results`, `max_uses`, `engine`, and `allowed_domains` / `excluded_domains`.

## Quick start

Use the OpenAI SDK against the AI Gateway base URL and call the Responses API directly.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What are the latest changes to the OpenAI Responses API?",
    "tools": [{ "type": "web_search_preview" }]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What are the latest changes to the OpenAI Responses API?",
  tools: [{ type: "web_search_preview" }],
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What are the latest changes to the OpenAI Responses API?",
    tools=[{"type": "web_search_preview"}],
)

print(response.output_text)
```

Endpoint:

`POST https://router.toqan.ai/eu/v3/router/responses`

## Tool definitions

Request `tools` entries use the discriminated **`type`** field, matching the gateway schema.

### `web_search_preview`

| Field | Type | Description |
| - | - | - |
| `type` | `"web_search_preview"` | Identifies the preview web search tool. |
| `domains` | string\[] | Optional allowlist of domains to restrict search. |
| `search_context_size` | string | Optional. One of `low`, `medium`, `high`. Controls how much context to retrieve per result. |
| `user_location` | object | Optional. Hints for localized results (`type`, `city`, `country`, `region`, `timezone`). |

### `web_search`

| Field | Type | Description |
| - | - | - |
| `type` | `"web_search"` | Stable web search tool type. |
| `search_context_size` | string | Optional. `low`, `medium`, `high`. |
| `user_location` | object | Optional. Same shape as above. |
| `filters` | object | Optional. e.g. `allowed_domains` (nullable array) to restrict domains. |

> [!WARNING]
>
> The **AI Gateway** accepts the full tool object on `/responses`. **OpenAI** requests pass tools through to the upstream Responses API. **Anthropic** and **Google** paths map `web_search` / `web_search_preview` to native web search tools; fields the upstream API does not support may be ignored.

## `include` (optional)

You can ask for additional fields on web search output items, aligned with OpenAI Responses `include`:

| Value | Meaning |
| - | - |
| `web_search_call.results` | Include detailed search results where available. |
| `web_search_call.action.sources` | Include source URLs and titles on the action. |

Example request body:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "openai/gpt-5.6-sol",
  "input": "Summarize today’s headlines in finance.",
  "tools": [{ "type": "web_search_preview" }],
  "include": ["web_search_call.action.sources"]
}
```

## Output: `web_search_call`

Responses can contain output items with `"type": "web_search_call"`:

| Field | Description |
| - | - |
| `id` | Item id. |
| `type` | `"web_search_call"`. |
| `status` | Lifecycle status for the call. |
| `action` | Optional. `type` may be `search`, `open_page`, or `find`, plus fields like `query`, `url`, `pattern`, and `sources` (url + title). |

Exact payload shape matches what the provider returns; streaming uses the same event model as other `/responses` streams.

## Provider behavior

### OpenAI

Send `tools` and `include` in the request body with the model id (for example `openai/gpt-5.6-sol`). Use the same parameters OpenAI documents for [web search](https://platform.openai.com/docs/guides/tools-web-search) on the Responses API.

> [card] [OpenAI](/docs/ai-studio/integrations/providers/openai.md)
>
> Set up your OpenAI API key to use GPT-5.6 Sol with web search.

### Anthropic

`web_search` and `web_search_preview` in `tools` are mapped to Anthropic’s web search tool for the Messages path used under `/responses`.

> [card] [Anthropic](/docs/ai-studio/integrations/providers/anthropic.md)
>
> Set up your Anthropic API key to use Claude with web search.

### Google Gemini

The same tool types enable **Google Search grounding** (`googleSearch`) for Gemini models that support it.

> [card] [Google AI](/docs/ai-studio/integrations/providers/google-ai.md)
>
> Set up your Google AI API key to use Gemini models with Google Search grounding.

## `tool_choice`

You can steer the model toward web search using the structured `tool_choice` form, for example:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tool_choice": { "type": "web_search_preview" }
}
```

Supported `tool_choice.type` values for built-in tools are defined in the API schema (including `web_search`, `web_search_preview`, and related literals). Strings `none`, `auto`, and `required` behave as usual.

## Streaming

Set **`"stream": true`** on the same JSON body. The server responds with **`text/event-stream`** and events in the OpenAI-style response stream format.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -N -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the current phase of the moon for San Francisco?",
    "tools": [{ "type": "web_search_preview" }],
    "stream": true
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const stream = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What is the current phase of the moon for San Francisco?",
  tools: [{ type: "web_search_preview" }],
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

stream = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What is the current phase of the moon for San Francisco?",
    tools=[{"type": "web_search_preview"}],
    stream=True,
)

for event in stream:
    print(event)
```

> [!NOTE]
>
> For cURL streaming, `-N` disables buffering so SSE lines show up as they arrive. Parse `data:` lines from the response body the same way you would against OpenAI’s Responses stream.

## Code examples

Set **`TOQAN_API_KEY`** (or pass the key explicitly) so the `Authorization` header resolves.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the current phase of the moon for San Francisco?",
    "tools": [{ "type": "web_search_preview" }],
    "include": ["web_search_call.action.sources"]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What is the current phase of the moon for San Francisco?",
  tools: [{ type: "web_search_preview" }],
  include: ["web_search_call.action.sources"],
});

console.log(response.output_text);

for (const item of response.output ?? []) {
  if (item.type === "web_search_call") {
    console.log("web_search_call", item.action);
  }
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What is the current phase of the moon for San Francisco?",
    tools=[{"type": "web_search_preview"}],
    include=["web_search_call.action.sources"],
)

print(response.output_text)

for item in response.output or []:
    if item.type == "web_search_call":
        print("web_search_call", item.action)
```

## See also

* [Responses API](/docs/ai-gateway/features/responses-api.md): the endpoint web search runs on, and when to choose it over Chat Completions
* [OpenAI-Compatible API](/docs/ai-gateway/features/openai-compatible-api.md): base URL and `/responses`
* [Reasoning](/docs/ai-gateway/features/reasoning.md): `reasoning` for OpenAI models via Responses API; `thinking` for Anthropic and Google Gemini via Chat Completions
* [Tool Calling](/docs/ai-gateway/features/tool-calling.md): function tools on `/chat/completions` and `/responses`
* [Web search server tool](/docs/ai-gateway/features/server-tools/web-search.md): the gateway-run `orq:web_search` contract on Chat Completions


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