opendunes
Helpers · 3 min
Copy page ▾

Web search

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

  1. What it does.
  2. Name it in tools.
  3. Set how many searches.
  4. Read what it bills on.

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.

Typeopendunes:web_search
Routes/v1/chat/completions, /v1/responses and /v1/messages
A stepone search
Stepsat most 30 a request
Bills oneach 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 sendHolds
max_tool_callsfewer steps than 30, for the whole request
stop_server_tools_whenconditions 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 requestThe hold
names max_tool_callsholds 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_callspays 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

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.

Do

Name the helper only on the requests that need fresh facts, and set max_tool_calls to the number of searches the question deserves.