Web search gives your AI assistant access to real-time information from the internet. Use it for current events, live data, recent documentation, and anything beyond the model's training cutoff.
Enable web search on an assistant via the tools configuration or pass it in the request:
{
"organization_id": "org_your_org_id",
"assistant_id": "asst_abc123",
"tools": [{"type": "web_search"}],
"inputs": [{"role": "user", "content": "What is the current price of Bitcoin?"}]
}| Mode | Behavior |
|---|---|
auto | Model decides when to search (recommended) |
on | Always search before responding |
off | Never search |
{
"tools": [{"type": "web_search", "mode": "auto"}]
}When the model decides to use web search:
- It formulates one or more search queries
- The results appear in the response as
web_search_calloutput items - The model synthesizes the results into its final response
You can inspect the search results via response.output items of type web_search_call.
{
"output": [
{
"type": "web_search_call",
"id": "ws_abc123",
"status": "completed"
},
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Based on current data, Bitcoin is trading at..."
}
]
}
]
}- Current events — News, market data, sports scores
- Documentation lookups — Latest API docs, package changelogs
- Fact verification — Cross-check model claims against live sources
- Research — Gather recent information on any topic
You can restrict or expand the sources the search queries, for example limiting results to specific domains. This is configured via web_search_call.action.sources on the assistant or request level.
- System Tools Overview — All available built-in tools
- File Search — Search through uploaded documents
- Assistants — Configuring tools on an assistant
- Agentic Workflows — Multi-step tool use