Web search
Let the model search the web in the middle of its answer, and pay for each search.
This page is one helperHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on Helpers →. The list of helpers, and how the charge adds up, sit in 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 DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → |
Your code runs nothing and sends no result back. The helper replaces the web plugin and the :online suffix: 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.
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"])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 balanceBalanceWhat you can spend, in DA.More on Balance and charges →, 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.
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.
Name the helper only on the requests that need fresh facts, and set max_tool_calls to the number of searches the question deserves.