# Responses · web search

`POST /v1/responses` with the `opendunes:web_search` helper in `tools` lets the model search the
web while it answers, and returns a reply that cites the pages it read.

## Request

Send it with an API key, as JSON, like any request on the route: [Responses](/docs/reference/responses)
lists every field, and the [Text](/docs/text) guide walks through a first call. OpenDunes runs
the search: the model decides whether to search and how often, reads the results, then
writes its reply. You send no result back.

| Field | Needed | You send |
|---|---|---|
| `tools` | yes | a list holding `{"type": "opendunes:web_search"}`, with its settings in `parameters` when you set any, beside your own functions |
| `max_tool_calls` | no | 1 to 30, 30 when not sent: the most helper steps the request may take, each search one step |

The helper's `parameters`, each optional:

| Field | Needed | You send |
|---|---|---|
| `engine` | no | `auto`, the default: the provider's own search where the model has one, else `exa`. Or `native`, `exa`, `parallel` or `perplexity`; `firecrawl` is not offered |
| `max_results` | no | 1 to 25, 5 when not sent: the results one search returns; up to 20 with `perplexity`, and ignored by a provider's own search |
| `max_uses` | no | the most searches the model may run in this request |
| `max_total_results` | no | the most results across every search in this request |
| `search_context_size` | no | `low`, `medium` or `high`: how much of each page the model reads, with `exa`, `parallel` and `perplexity` |
| `max_characters` | no | 1 to 100 000: the most characters read from each result, with `exa`, `parallel` and `perplexity`; it wins over `search_context_size` |
| `user_location` | no | an approximate place, to bias the results toward it, with a provider's own search only |
| `allowed_domains` | no | only these sites, such as `["ouedkniss.com"]` |
| `excluded_domains` | no | never these sites; most engines take one list or the other, not both |

When a search limit is reached, the next search the model asks for is not run: the model is
told so, and answers with what it has.

The `web` plugin and the `:online` suffix searched before the helper did. The helper replaces
both.

Souk Bot checks the weekend's weather before it suggests a jacket:

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/responses"
MODEL = "anthropic/claude-sonnet-4.5"
QUESTION = "Will Oran be cold this weekend? Which jacket should I buy?"

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "input": QUESTION,
            "tools": [
                {
                    "type": "opendunes:web_search",
                    "parameters": {"max_results": 3, "max_uses": 2},
                }
            ],
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for item in answer["output"]:
    if item["type"] == "message":
        part = item["content"][0]
        print(part["text"])
        for note in part.get("annotations", []):
            print(note["url"])
usage = answer["usage"]
print(usage["server_tool_use_details"]["web_search_requests"])
print(usage["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";
const QUESTION =
  "Will Oran be cold this weekend? Which jacket should I buy?";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    input: QUESTION,
    tools: [
      {
        type: "opendunes:web_search",
        parameters: { max_results: 3, max_uses: 2 },
      },
    ],
  }),
});
const answer = await response.json();

for (const item of answer.output) {
  if (item.type !== "message") continue;
  const part = item.content[0];
  console.log(part.text);
  for (const note of part.annotations ?? []) console.log(note.url);
}
console.log(answer.usage.server_tool_use_details.web_search_requests);
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address  = "https://opendunes.com/v1/responses"
	model    = "anthropic/claude-sonnet-4.5"
	question = "Will Oran be cold this weekend? Which jacket should I buy?"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	webSearch := map[string]any{
		"type":       "opendunes:web_search",
		"parameters": map[string]int{"max_results": 3, "max_uses": 2},
	}

	body, err := json.Marshal(map[string]any{
		"model": model,
		"input": question,
		"tools": []any{webSearch},
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Output []struct {
			Type    string `json:"type"`
			Content []struct {
				Text        string `json:"text"`
				Annotations []struct {
					URL string `json:"url"`
				} `json:"annotations"`
			} `json:"content"`
		} `json:"output"`
		Usage struct {
			ServerToolUseDetails struct {
				WebSearchRequests int `json:"web_search_requests"`
			} `json:"server_tool_use_details"`
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}

	for _, item := range answer.Output {
		if item.Type != "message" || len(item.Content) == 0 {
			continue
		}
		fmt.Println(item.Content[0].Text)
		for _, note := range item.Content[0].Annotations {
			fmt.Println(note.URL)
		}
	}
	fmt.Println(answer.Usage.ServerToolUseDetails.WebSearchRequests)
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/responses"
MODEL="anthropic/claude-sonnet-4.5"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input": "Will Oran be cold this weekend? Which jacket should I buy?",
    "tools": [
      {
        "type": "opendunes:web_search",
        "parameters": {"max_results": 3, "max_uses": 2}
      }
    ]
  }'
```

## Response

`200 OK`, once the reply is written. `output` holds an `opendunes:web_search` item for each
search, then the `message` with the reply, its sources in `annotations`. Illustrative:

```json
{
  "output": [
    {
      "type": "opendunes:web_search",
      "id": "ws_2a8f0c11",
      "status": "completed",
      "action": {
        "type": "search",
        "query": "Oran weather forecast this weekend",
        "sources": [{"type": "url", "url": "https://www.example.com/oran"}]
      }
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Nights drop to 9 °C this weekend: take the lined jacket.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.example.com/oran",
              "title": "Oran: weather this weekend",
              "start_index": 0,
              "end_index": 31,
              "content": "Saturday night 9 °C, Sunday night 10 °C…"
            }
          ]
        }
      ]
    }
  ],
  "usage": {
    "server_tool_use_details": {
      "tool_calls_requested": 1,
      "tool_calls_executed": 1,
      "web_search_requests": 1
    },
    "cost": 1.92
  }
}
```

| Field | Holds |
|---|---|
| `action` | in each `opendunes:web_search` item: what the search did |
| `query` | in `action`: the words the model searched for |
| `sources` | in `action`: the pages the search returned, each a `url`, when the engine lists them |
| `annotations` | in each `output_text` part of the reply: the sources it cites |
| `url_citation` | the `type` of a cited source |
| `url` | the page cited |
| `title` | the page's title |
| `start_index` · `end_index` | where, in the part's `text`, the words that rest on it begin and end |
| `content` | the passage the model read from the page, when the engine returns one |
| `server_tool_use_details` | in `usage`: the helper calls requested and run |
| `web_search_requests` | in `server_tool_use_details`: the searches run |
| `cost` | in `usage`: the charge, in DA, the model's tokens and every search |

**With `stream: true`.** Each search opens and closes as an item, with
`response.output_item.added` and `response.output_item.done`; the reply follows in
`response.output_text.delta` events, and each citation arrives as
`response.output_text.annotation.added`. `response.completed` ends the stream with `usage`.

## What it cost

One charge in DA from your balance once the reply is delivered: the model's tokens at its
rates, which its model page shows, and each search, billed per search. `usage.cost` carries
the whole charge.

- **Moves the count**: the searches the model runs, which `max_uses` and `max_tool_calls`
  bound; the results it reads, counted as input tokens, which `max_results`,
  `max_total_results`, `search_context_size` and `max_characters` bound; `engine`, where
  engines are metered apart.
- **Changes the answer, never the bill**: `allowed_domains`, `excluded_domains` and
  `user_location`.

A request that searched nothing is charged its tokens only.

## Errors

An error keeps the Responses shape: [Responses · errors](/docs/reference/responses-errors)
lists every status and every word.

| Status | When |
|---|---|
| 400 | `engine` is `firecrawl` or is not one on offer, a setting has the wrong type or is out of range, or `max_tool_calls` is not 1 to 30 |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; `metadata.limit_source`, beside `error`, names which, and `deposit_url` or `key_url` there says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries `Retry-After: 60` |
| 403 | the key is kept to other models, a guardrail's budget is spent, or a guardrail or a filter blocked the request |
| 404 | `model` is not a model on sale |
