Responses · web search
POST /v1/responses with the opendunes:web_search 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 → 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 keyAPI keyThe key you create and send with every request that calls a model.More on API keys →, as JSON, like any request on the route: Responses lists every field, and the 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:
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"])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:
{
"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 DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, 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 balanceBalanceWhat you can spend, in DA.More on Balance and charges → 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_usesandmax_tool_callsbound; the results it reads, counted as input tokens, whichmax_results,max_total_results,search_context_sizeandmax_charactersbound;engine, where engines are metered apart. - Changes the answer, never the bill:
allowed_domains,excluded_domainsanduser_location.
A request that searched nothing is charged its tokens only.
Errors
An error keeps the Responses shape: 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 |
Last modified on