> ## 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 Search Server Tool

> Let models search the web during a request.

Use `phaseo:web_search` when the model needs current or source-backed information. The model decides when to search, writes the query, and can search multiple times in one request.

Phaseo returns URLs, titles, snippets, highlights, and optional page text to the model so it can write a grounded response.

> [!NOTE]
>
> TinyFish Search is available as an optional managed engine. Provider-native search remains available through `engine: "native"` on supported routes.

## How it works

1. Add `{ "type": "phaseo:web_search" }` to `tools`.
2. The model decides whether it needs a search and emits a query.
3. Phaseo executes the search using the configured engine.
4. Results are returned to the model as tool context.
5. The model writes the final response and may search again 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": "What were the major AI announcements this week?" }
    ],
    "tools": [
      { "type": "phaseo:web_search" }
    ]
  }'
```

## Configuration

```json theme={null}
{
  "type": "phaseo:web_search",
  "parameters": {
    "engine": "exa",
    "max_results": 5,
    "max_total_results": 15,
    "search_context_size": "medium",
    "max_characters": 2048,
    "allowed_domains": ["arxiv.org", "nature.com"],
    "excluded_domains": ["reddit.com"],
    "include_highlights": true,
    "include_text": false
  }
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `engine` | string | `exa` | Search engine: `auto`, `native`, `exa`, `parallel`, `firecrawl`, `perplexity`, or `tinyfish`. |
| `max_results` | integer | `5` | Maximum results returned per search call. |
| `max_total_results` | integer | `10` | Maximum cumulative results across the server-tool loop. |
| `max_uses` | integer | `10` | Maximum search calls across the server-tool loop. |
| `search_context_size` | string | `medium` | Context size for engines that support highlight sizing: `low`, `medium`, or `high`. |
| `max_characters` | integer | engine default | Maximum text characters per result when text is included. |
| `allowed_domains` | string\[] | none | Only return results from these domains. Alias: `include_domains`. |
| `excluded_domains` | string\[] | none | Exclude results from these domains. Alias: `exclude_domains`. |
| `include_highlights` | boolean | `true` | Include engine-provided highlights/snippets when available. |
| `include_text` | boolean | `false` | Include fuller result text when the engine supports it. |
| `user_location` | object | none | Optional location hint for engines that support localized search. |
| `language` | string | none | TinyFish language hint, such as `en`. |
| `page` | integer | `0` | TinyFish result page, from `0` through `10`. |

## Engine selection

| Engine | Behavior |
| - | - |
| `exa` | Managed Exa search. Requires Phaseo to have Exa configured for the gateway runtime. |
| `auto` | Uses the configured managed default, currently Exa. |
| `parallel` | Uses Parallel search when configured. |
| `firecrawl` | Uses Firecrawl search when configured. |
| `perplexity` | Uses the first-party Perplexity Search API when configured. Supports ranked results, `search_context_size`, regional search from `user_location.country`, and either allowed or excluded domains. |
| `tinyfish` | Uses TinyFish Search when `TINYFISH_API_KEY` is configured. Supports localized, paginated ranked results and translates `allowed_domains` / `excluded_domains` into search operators. TinyFish Search does not supply full page text; use `phaseo:web_fetch` when fuller content is needed. |
| `native` | Converts the declaration to a provider-native web-search tool before the upstream model call when the request surface supports it. On Chat Completions and Responses, the request goes only to providers that run web search themselves; if none serve the model, Phaseo runs its default search engine instead and bills it as a managed search. |

Use `engine: "native"` only in the tool declaration. If a model tries to pass `engine: "native"` inside an already-emitted gateway search call, Phaseo returns a tool error because native tools must be selected before the upstream request is sent.

## TinyFish Search

Enable the engine by configuring `TINYFISH_API_KEY` in your Phaseo gateway runtime secrets, then select it in the tool parameters:

```json theme={null}
{
  "type": "phaseo:web_search",
  "parameters": {
    "engine": "tinyfish",
    "language": "en",
    "page": 0,
    "max_results": 5,
    "allowed_domains": ["phaseo.app", "github.com"],
    "excluded_domains": ["reddit.com"]
  }
}
```

`language` provides a locale hint and `page` selects a result page from `0` through `10`. TinyFish supports both domain-filter lists; Phaseo converts them into search operators. Results include URLs, titles, and snippets/highlights. Use `phaseo:web_fetch` when the model needs fuller text from a result.

## Domain filtering

Use `allowed_domains` when the answer must come from a controlled source set:

```json theme={null}
{
  "type": "phaseo:web_search",
  "parameters": {
    "allowed_domains": ["phaseo.app", "github.com"]
  }
}
```

Use `excluded_domains` when broad web search is allowed but specific domains should be removed from the result set.

Perplexity and Firecrawl accept either `allowed_domains` or `excluded_domains` in a single search call, not both. Perplexity accepts up to 20 domain filters per request and maps excluded domains to its denylist format. TinyFish translates both arrays to `site:` and `-site:` operators in the query.

TinyFish Search is free on its published plans, so Phaseo does not add a provider usage charge for `engine: "tinyfish"`; normal Phaseo request and token pricing still applies.

## Responses API

The same tool shape works with `/v1/responses`:

```json theme={null}
{
  "model": "openai/gpt-5-nano",
  "input": "Find the latest release notes for Phaseo.",
  "tools": [
    { "type": "phaseo:web_search", "parameters": { "max_results": 4 } }
  ]
}
```

## Usage and pricing

Web search calls increment:

```json theme={null}
{
  "usage": {
    "server_tool_use": {
      "web_search_requests": 1,
      "web_search_results": 5,
      "web_search_extra_results": 0
    }
  }
}
```

Managed search pricing can use `server_tool_web_search_requests` and `server_tool_web_search_extra_results`. Provider-native search usage can use `native_web_search_requests` where a model price card defines that meter.

## Related

* [Web Fetch](https://phaseo.app/docs/v1/guides/server-tools/web-fetch.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.