# Web search

Let the model search the web in the middle of its answer, and pay for each search.

1. [What it does](#1-what-it-does).
2. [Name it in `tools`](#2-name-it-in-tools).
3. [Set how many searches](#3-set-how-many-searches).
4. [Read what it bills on](#4-read-what-it-bills-on).

This page is one helper. The list of helpers, and how the charge adds up, sit in [Helpers](/docs/helpers).

## 1. What it does

The model decides when a question needs the web. It writes a search, OpenDunes runs it, and the model reads the results before it goes on. It may search again with a better question. When it has enough, it answers and cites what it read.

| | |
|---|---|
| Type | `opendunes:web_search` |
| Routes | `/v1/chat/completions`, `/v1/responses` and `/v1/messages` |
| A step | one search |
| Steps | at most 30 a request |
| Bills on | each search, in DA |

Your code runs nothing and sends no result back. The helper replaces the `web` plugin and the `:online` suffix: [Plugins](/docs/plugins).

## 2. Name it in `tools`

Souk Bot lets the model look up a price before it quotes one. The sample names the helper beside no function of its own, allows three searches, and prints the answer, how many searches ran and the charge.

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

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "What does an iPhone 16 cost in Algiers today? Cite sources."

body = {
    "model": MODEL,
    "messages": [{"role": "user", "content": PROMPT}],
    "tools": [{"type": "opendunes:web_search"}],
    "max_tool_calls": 3,
}
request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

print(answer["choices"][0]["message"]["content"])
print(answer["usage"]["server_tool_use"])
print(answer["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "What does an iPhone 16 cost in Algiers today? Cite sources.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    messages: [{ role: "user", content: PROMPT }],
    tools: [{ type: "opendunes:web_search" }],
    max_tool_calls: 3,
  }),
});
const answer = await response.json();

console.log(answer.choices[0].message.content);
console.log(answer.usage.server_tool_use);
console.log(answer.usage.cost);
```

```go
package main

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

const (
	address = "https://opendunes.com/v1/chat/completions"
	model   = "anthropic/claude-sonnet-4.5"
	prompt  = "What does an iPhone 16 cost in Algiers today? Cite sources."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	body, err := json.Marshal(map[string]any{
		"model": model,
		"messages": []map[string]string{
			{"role": "user", "content": prompt},
		},
		"tools": []map[string]string{
			{"type": "opendunes:web_search"},
		},
		"max_tool_calls": 3,
	})
	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 {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			ServerToolUse map[string]int `json:"server_tool_use"`
			Cost          json.Number    `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	fmt.Println(answer.Choices[0].Message.Content)
	fmt.Println(answer.Usage.ServerToolUse)
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
PROMPT="What does an iPhone 16 cost in Algiers today? Cite sources."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ],
    "tools": [
      {
        "type": "opendunes:web_search"
      }
    ],
    "max_tool_calls": 3
  }'
```

The answer is a `200`. `usage.server_tool_use.web_search_requests` counts the searches that ran.

Name the helper by its type, `opendunes:web_search`. Any other spelling of the type is a `400`.

## 3. Set how many searches

A request runs at most 30 steps, and a search is one step. Two fields change that.

| You send | Holds |
|---|---|
| `max_tool_calls` | fewer steps than 30, for the whole request |
| `stop_server_tools_when` | conditions that end the steps early; when sent, it replaces `max_tool_calls` |

When the steps run out, the model answers with what it has gathered.

A search engine that bills an account of your own elsewhere is not offered. A request that names one is refused with a `400`.

## 4. Read what it bills on

One charge, in DA, from your balance, the moment the answer ends: the model's tokens and each search. `usage.cost` carries the whole of it. The Plugins tab of your dashboard's Gateway page lists the helper with its price.

Before the model starts, OpenDunes holds money from your wallet for the words, the answer and the searches. The hold sets the steps your wallet can pay.

| Your request | The hold |
|---|---|
| names `max_tool_calls` | holds that many steps whole; when the wallet cannot pay them, the answer is a `402` that says what the request needs |
| names no `max_tool_calls` | pays as many steps as the wallet can, up to 30; when that is fewer than 30, the request runs with `max_tool_calls` lowered to it |

A search has no spend cap of its own: its steps are the limit. The model reads its results as tokens, so a request with many searches also bills more input.

<div class="dont">
<p>Don't give a model web search for a question it can answer without it. It decides how often to search, and every search is charged.</p>
</div>

<div class="do">
<p>Name the helper only on the requests that need fresh facts, and set <code>max_tool_calls</code> to the number of searches the question deserves.</p>
</div>
