# Web fetch

Let the model read a web page by its address in the middle of its answer, and pay for each page.

1. [What it does](#1-what-it-does).
2. [Name it in `tools`](#2-name-it-in-tools).
3. [Limit the pages](#3-limit-the-pages).
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

When the model needs the content of an address, one in your prompt or one a search found, it asks for it. OpenDunes reads the page, and the text, the title and the address go back to the model before it goes on.

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

Your code reads no page and sends no result back.

## 2. Name it in `tools`

Souk Bot summarizes a news agency's front page. The sample names the helper, caps the pages at two and the length of each page at about four thousand tokens, then prints the answer, the number of calls 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 = "Summarise https://www.aps.dz in three lines."

body = {
    "model": MODEL,
    "messages": [{"role": "user", "content": PROMPT}],
    "tools": [
        {
            "type": "opendunes:web_fetch",
            "parameters": {"max_uses": 2, "max_content_tokens": 4000},
        }
    ],
}
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 = "Summarise https://www.aps.dz in three lines.";

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_fetch",
        parameters: { max_uses: 2, max_content_tokens: 4000 },
      },
    ],
  }),
});
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  = "Summarise https://www.aps.dz in three lines."
)

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]any{
			{
				"type": "opendunes:web_fetch",
				"parameters": map[string]int{
					"max_uses":           2,
					"max_content_tokens": 4000,
				},
			},
		},
	})
	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="Summarise https://www.aps.dz in three lines."

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_fetch",
        "parameters": {
          "max_uses": 2,
          "max_content_tokens": 4000
        }
      }
    ]
  }'
```

The answer is a `200`. Name the helper by its type, `opendunes:web_fetch`; any other spelling of the type is a `400`.

## 3. Limit the pages

Put these in the helper's `parameters`.

| Parameter | Does |
|---|---|
| `max_uses` | pages the model may read in the request |
| `max_content_tokens` | cuts a page longer than this, in approximate tokens |
| `allowed_domains` | only these sites |
| `blocked_domains` | never these sites |
| `engine` | who reads the page: `auto` is the default, `opendunes` reads it directly |

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

A request runs at most 30 steps, and a page read is one step. Two fields on the request lower that for every helper in it.

| 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` |

## 4. Read what it bills on

One charge, in DA, from your balance, the moment the answer ends: the model's tokens and each page read. The page the model reads is input tokens, so a long page costs more than a short one; `max_content_tokens` is how you bound that. `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 page reads. 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 page read has no spend cap of its own: its steps are the limit.

<div class="dont">
<p>Don't leave <code>max_content_tokens</code> out when the model may read long pages. Every page is read in full and charged as input.</p>
</div>

<div class="do">
<p>Pair it with <a href="/docs/web-search">Web search</a>: the model searches, then reads only the pages worth reading.</p>
</div>
