opendunes
Overview
Copy page ▾

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.

FieldNeededYou send
toolsyesa list holding {"type": "opendunes:web_search"}, with its settings in parameters when you set any, beside your own functions
max_tool_callsno1 to 30, 30 when not sent: the most helper steps the request may take, each search one step

The helper's parameters, each optional:

FieldNeededYou send
enginenoauto, 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_resultsno1 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_usesnothe most searches the model may run in this request
max_total_resultsnothe most results across every search in this request
search_context_sizenolow, medium or high: how much of each page the model reads, with exa, parallel and perplexity
max_charactersno1 to 100 000: the most characters read from each result, with exa, parallel and perplexity; it wins over search_context_size
user_locationnoan approximate place, to bias the results toward it, with a provider's own search only
allowed_domainsnoonly these sites, such as ["ouedkniss.com"]
excluded_domainsnonever 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:

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
  }
}
FieldHolds
actionin each opendunes:web_search item: what the search did
queryin action: the words the model searched for
sourcesin action: the pages the search returned, each a url, when the engine lists them
annotationsin each output_text part of the reply: the sources it cites
url_citationthe type of a cited source
urlthe page cited
titlethe page's title
start_index · end_indexwhere, in the part's text, the words that rest on it begin and end
contentthe passage the model read from the page, when the engine returns one
server_tool_use_detailsin usage: the helper calls requested and run
web_search_requestsin server_tool_use_details: the searches run
costin 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_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 lists every status and every word.

StatusWhen
400engine 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
401the key is missing, wrong, disabled or expired
402your 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
403the key is kept to other models, a guardrail's budget is spent, or a guardrail or a filter blocked the request
404model is not a model on sale

Last modified on