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

# Web search

Add `{"type": "web_search"}` to `tools`. The model decides when to search, Hopper runs each search, and the response carries the answer with its sources.

## Quickstart

```bash cURL theme={null}
curl https://api.withhopper.com/v1/chat/completions \
  -H "Authorization: Bearer $HOPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017",
    "messages": [{"role": "user", "content": "Who won the last F1 race?"}],
    "tools": [{"type": "web_search"}]
  }'
```

```python Python theme={null}
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.withhopper.com/v1",
    api_key=os.environ["HOPPER_API_KEY"],
)

response = client.chat.completions.create(
    model="deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "Who won the last F1 race?"}],
    tools=[{"type": "web_search"}],
)

message = response.choices[0].message
print(message.content)
for annotation in message.annotations or []:
    print(annotation.url_citation.url)
```

```typescript TypeScript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.withhopper.com/v1",
  apiKey: process.env.HOPPER_API_KEY,
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash-1017",
  messages: [{ role: "user", content: "Who won the last F1 race?" }],
  tools: [{ type: "web_search" } as any],
});

const message = response.choices[0].message;
console.log(message.content);
for (const annotation of message.annotations ?? []) {
  console.log(annotation.url_citation.url);
}
```

> [accordion] Sample response
>
> ```json theme={null}
> {
>   "id": "chatcmpl-a5b48c583395c06f",
>   "object": "chat.completion",
>   "created": 1793917119,
>   "model": "deepseek-v4.1-flash-1017",
>   "choices": [
>     {
>       "index": 0,
>       "finish_reason": "stop",
>       "message": {
>         "role": "assistant",
>         "content": "Max Verstappen won the most recent Formula 1 Grand Prix, taking victory at the Mexico City Grand Prix for Red Bull ahead of Lewis Hamilton [3].",
>         "annotations": [
>           {
>             "type": "url_citation",
>             "url_citation": {
>               "url": "https://www.formula1.com/en/latest/article/antonelli-crowned-youngest-ever-f1-champion-as-verstappen-wins-eventful-mexico-city-grand-prix.xpMMeef0KmRURs9IDs3LH",
>               "title": "2026 Formula 1 Mexico City Grand Prix: Kimi Antonelli crowned youngest F1 champion as Max Verstappen wins eventful Mexico City Grand Prix",
>               "content": "2026 Formula 1 Mexico City Grand Prix: Kimi Antonelli crowned youngest F1 champion as Max Verstappen wins eventful Mexico City Grand Prix # Antonelli crowned youngest ever F1 champion as Verstappen wi",
>               "start_index": 139,
>               "end_index": 142
>             }
>           }
>         ]
>       }
>     }
>   ],
>   "usage": {
>     "prompt_tokens": 2053,
>     "completion_tokens": 149,
>     "total_tokens": 2202,
>     "prompt_tokens_details": {
>       "cached_tokens": 512
>     },
>     "completion_tokens_details": {
>       "reasoning_tokens": 69
>     },
>     "server_tool_use": {
>       "web_search_requests": 1
>     }
>   }
> }
> ```

## Tool options

Set these on the `web_search` tool object, for example `{"type": "web_search", "max_uses": 2}`.

**type** `string` *required*

`web_search`, or `openrouter:web_search` with these options inside `parameters`.

**max\_uses** `integer` (default: 5)

Searches per request, up to 10. After the last one the model answers with the results it has.

**max\_results** `integer` (default: 5)

Results per search, up to 10.

**allowed\_domains** `string[]`

Only return results from these domains.

**excluded\_domains** `string[]`

Never return results from these domains.

**search\_context\_size** `string` (default: medium)

Page text passed to the model per result: `low`, `medium` or `high`.

`plugins: [{"id": "web"}]` takes the same options and always searches before the first answer.

## Response fields

**choices\[].message.annotations** `object[]`

One `url_citation` per source.

**url\_citation**

**url** `string`

Source URL.

**title** `string`

Page title, or the URL when the page has none.

**content** `string`

First 200 characters of the page text.

**start\_index** `integer`

Start of the source's first `[n]` marker in `content`. `0` if the answer does not cite it.

**end\_index** `integer`

End of that marker.

**usage** `object`

Tokens summed over every model turn in the request.

**properties**

**server\_tool\_use.web\_search\_requests** `integer`

Searches run.

## Streaming

With `stream: true`, a `: searching` comment line is sent while each search runs, then the answer streams as usual. The last chunk carries `delta.annotations`.

## Function tools

Your own function tools can be sent alongside `web_search`. When the model calls one, the response returns `tool_calls` as usual; searches run before that are counted in `usage`.

## Anthropic Messages

`POST /v1/messages` accepts the `web_search_20250305` server tool.

```bash cURL theme={null}
curl https://api.withhopper.com/v1/messages \
  -H "x-api-key: $HOPPER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017",
    "max_tokens": 4000,
    "messages": [{"role": "user", "content": "Latest Node.js release?"}],
    "tools": [{"type": "web_search_20250305", "name": "web_search"}]
  }'
```

**max\_uses** `integer` (default: 5)

Searches per request, up to 10.

**allowed\_domains** `string[]`

Only return results from these domains. Cannot be combined with `blocked_domains`.

**blocked\_domains** `string[]`

Never return results from these domains.

Each search returns a `server_tool_use` block followed by a `web_search_tool_result` block. Text blocks cite sources with `web_search_result_location`. Send the content blocks back in later turns and the model can use the earlier results without searching again.

## OpenAI Responses

`POST /v1/responses` accepts the `web_search` tool.

```bash cURL theme={null}
curl https://api.withhopper.com/v1/responses \
  -H "Authorization: Bearer $HOPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017",
    "input": "Latest Python release?",
    "tools": [{"type": "web_search"}]
  }'
```

**filters.allowed\_domains** `string[]`

Only return results from these domains.

**filters.blocked\_domains** `string[]`

Never return results from these domains.

**search\_context\_size** `string` (default: medium)

Page text passed to the model per result: `low`, `medium` or `high`.

**external\_web\_access** `boolean` (default: true)

`false` turns search off.

`output` has one `web_search_call` item per search, then the `message` with `url_citation` annotations. Streaming sends `response.web_search_call.in_progress`, `.searching` and `.completed` for each search.

## Limits

| Limit | Value |
| :- | -: |
| Searches per request | 10 |
| Searches per minute, per organization | 120 |

A search over the per-minute limit is skipped and not billed; the model answers without it.

> [card] [Pricing](https://docs.withhopper.com/models.md#tools)
>
> Per-search price, billed on top of tokens.

> [card] [Errors](https://docs.withhopper.com/errors.md)
>
> Status codes and error bodies.


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