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.
Google native web search is not enabled in Phaseo server tools yet. Use managed search or provider-native search on supported OpenAI and Anthropic routes.
How it works
- Add
{ "type": "phaseo:web_search" } to tools.
- The model decides whether it needs a search and emits a query.
- Phaseo executes the search using the configured engine.
- Results are returned to the model as tool context.
- The model writes the final response and may search again if needed.
Quick start
curl https://api.phaseo.ai/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
{
"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, or perplexity. |
max_results | integer | 5 | Maximum results returned per search call. |
max_total_results | integer | 10 | Maximum cumulative results 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. |
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. |
native | Converts the declaration to a provider-native web-search tool before the upstream model call when the request surface supports it. |
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.
Domain filtering
Use allowed_domains when the answer must come from a controlled source set:
{
"type": "phaseo:web_search",
"parameters": {
"allowed_domains": ["phaseo.app", "github.com"]
}
}
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.
Responses API
The same tool shape works with /v1/responses:
{
"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:
{
"usage": {
"server_tool_use": {
"web_search_requests": 1,
"web_search_results": 5,
"web_search_extra_results": 0
}
}
}
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.
