> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Web Fetch Server Tool

> Let models fetch and read specific URLs during a request.

Use `phaseo:web_fetch` when the model needs to read a known URL, such as a documentation page, article, changelog, or PDF-like text source.

The model decides when to fetch, provides the URL, and receives bounded page text back as tool context.

## How it works

1. Add `{ "type": "phaseo:web_fetch" }` to `tools`.
2. The model decides whether it needs to fetch a URL.
3. Phaseo fetches and extracts the content using the configured engine.
4. The extracted text, title, URL, and truncation metadata are returned to the model.
5. The model writes the final response and may fetch more URLs if needed.

## Quick start

```bash theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      { "role": "user", "content": "Summarize https://phaseo.app/docs/v1/guides/tool-calling" }
    ],
    "tools": [
      { "type": "phaseo:web_fetch" }
    ]
  }'
```

## Configuration

```json theme={null}
{
  "type": "phaseo:web_fetch",
  "parameters": {
    "engine": "direct",
    "max_chars": 12000,
    "allowed_domains": ["phaseo.app"],
    "blocked_domains": ["internal.example.com"]
  }
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `engine` | string | surface-dependent | Fetch engine: `auto`, `native`, `direct`, `exa`, `parallel`, or `firecrawl`. |
| `max_chars` | integer | `12000` | Maximum extracted characters returned to the model. |
| `max_content_tokens` | integer | none | Token-style alias used when `max_chars` is omitted. |
| `max_uses` | integer | `10` | Maximum fetch calls across the server-tool loop. |
| `allowed_domains` | string\[] | none | Only allow fetches from these domains. |
| `blocked_domains` | string\[] | none | Reject fetches from these domains. Alias: `excluded_domains`. |

## Engine selection

| Engine | Behavior |
| - | - |
| `auto` | Uses Anthropic native fetch on `/v1/messages`; otherwise Exa if configured; otherwise direct gateway fetch. |
| `direct` | Fetches directly from the gateway runtime and extracts bounded text. |
| `exa` | Uses Exa content extraction when configured. |
| `parallel` | Uses Parallel Extract when configured. |
| `firecrawl` | Uses Firecrawl Scrape when configured. |
| `native` | Converts to Anthropic native `web_fetch_20260209` on `/v1/messages`. Other surfaces should use `direct` or a managed engine. |

Only HTTP(S) URLs are supported. Direct gateway fetch accepts text-like content types and reduces HTML to plain text before returning it to the model.

## Native Anthropic fetch

```json theme={null}
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Read the docs page and summarize the limits." }
  ],
  "tools": [
    {
      "type": "phaseo:web_fetch",
      "parameters": {
        "engine": "native",
        "max_content_tokens": 9000,
        "allowed_domains": ["phaseo.app"]
      }
    }
  ],
  "tool_choice": { "type": "tool", "name": "phaseo:web_fetch" }
}
```

## Tool result

Managed fetch returns a JSON tool result with fields such as:

```json theme={null}
{
  "provider": "fetch",
  "engine": "direct",
  "url": "https://phaseo.app/docs/v1/guides/tool-calling",
  "final_url": "https://phaseo.app/docs/v1/guides/tool-calling",
  "status": 200,
  "content_type": "text/html",
  "title": "Tool Calling",
  "text": "...",
  "truncated": false,
  "returned_chars": 8421
}
```

Check `truncated` before assuming the model received the full page.

## Usage and pricing

Web fetch calls increment:

```json theme={null}
{
  "usage": {
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}
```

Managed fetch pricing can use `server_tool_web_fetch_requests`. Provider-native fetch usage can use `native_web_fetch_requests` where a model price card defines that meter.

## Related

* [Web Search](https://phaseo.app/docs/v1/guides/server-tools/web-search.md)
* [Server Tools](https://phaseo.app/docs/v1/guides/server-tools/index.md)
* [Tool grounding with web fetch](https://phaseo.app/docs/v1/cookbook/tool-grounding-with-web-fetch.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.