Web Search

Overview

Web search is a built-in tool that allows models to search the web during a response. Unlike function tools, you don’t need to define a schema or handle execution yourself — the model searches the web automatically and incorporates the results into its answer. Add {"type": "web_search"} to your tools array to enable it. Concentrate can service the search two ways: with the model provider’s native web search, or with Concentrate’s own Exa-backed engine. By default it picks the best available for the model, so most models can search the web even when they have no native support. See Search engines to control this.

Prerequisites

Before using web search, ensure you have:

A Concentrate AI API key (get one here)
A model that supports web search (check the models endpoint)

Quick Start

curl https://api.concentrate.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "input": "What happened in the news today?",
    "tools": [
      {
        "type": "web_search"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.concentrate.ai/v1/responses",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-5.2",
        "input": "What happened in the news today?",
        "tools": [{"type": "web_search"}]
    }
)

data = response.json()
print(data)

const response = await fetch("https://api.concentrate.ai/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-5.2",
    input: "What happened in the news today?",
    tools: [{ type: "web_search" }]
  })
});

const data = await response.json();
console.log(data);

Tool Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"web_search"`
`engine`	object	No	Which search backend to use: `{"type": "auto"}` (default), `"native"`, or `"exa"`. See Search engines
`search_context_size`	string	No	Amount of search context: `"low"`, `"medium"`, or `"high"`. Defaults to provider behavior
`filters`	object	No	Filter search results by domain
`user_location`	object	No	Approximate user location for localized results

search_context_size, filters, and user_location are not supported natively by Google Vertex AI (Gemini) or Mistral models, and are silently ignored when those providers run the search themselves. To have them honored on any model, route the search through the Exa engine.

Search Context Size

Controls how much search context the model uses. Higher values may return more detailed results but use more tokens.

{
  "type": "web_search",
  "search_context_size": "medium"
}

Domain Filtering

Restrict search results to specific domains:

{
  "type": "web_search",
  "filters": {
    "allowed_domains": ["wikipedia.org", "bbc.com"]
  }
}

User Location

Provide an approximate location for more relevant local results:

{
  "type": "web_search",
  "user_location": {
    "type": "approximate",
    "country": "US",
    "region": "California",
    "city": "San Francisco",
    "timezone": "America/Los_Angeles"
  }
}

All user_location fields are optional.

Search engines

The optional engine field controls which backend runs the search:

`engine.type`	Behavior
`auto` (default)	Use the provider’s native web search when the model supports it; otherwise fall back to Concentrate’s Exa engine.
`native`	Always use the provider’s built-in web search. Requires a model that supports it.
`exa`	Always use Concentrate’s Exa-backed engine, regardless of provider.

{
  "type": "web_search",
  "engine": { "type": "exa" }
}

Exa engine

Concentrate runs its own web search through Exa. This is what lets models with no native web search still search the web: under auto, Concentrate transparently runs the search for them. Set engine.type to "exa" to force this path even on models that support native search — useful for consistent behavior across providers. Mechanically, Concentrate exposes an exa_web_search function tool to the model in place of the built-in tool. When the model calls it, Concentrate runs the query against Exa, feeds the results back, and repeats until the model stops searching or a turn limit is reached. The response you get back is identical to native search: a web_search_call item followed by the model’s answer, with the source URLs attached. Because Concentrate runs these searches itself, search_context_size, filters, and user_location are honored on every model routed through Exa — including Gemini and Mistral, which ignore them natively. search_context_size maps to the number of results fetched per query: low = 3, medium = 5 (default), high = 10.

Pricing

Exa searches are billed separately from tokens, as exa_web_search tool calls, at **

7.00 per 1,000 queries** (

0.007 per query). Each query in a search counts as one call. The count is reported in the response usage:

{
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567,
    "tool_calls": { "exa_web_search": 2 },
    "total_tokens": 1801
  }
}

Provider-native searches are billed by the provider through their normal pricing and appear under web_search instead.

Response Format

When the model performs a web search, the response output array includes a web_search_call item:

{
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_abc123",
      "status": "completed",
      "action": {
        "type": "search",
        "query": "latest news today",
        "sources": [
          {
            "type": "url",
            "url": "https://example.com/article"
          }
        ]
      }
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Here's what's happening today..."
        }
      ]
    }
  ]
}

The sources array contains the URLs the model referenced. Use these to provide citations in your application.

Combining with Function Tools

Web search works alongside function tools in the same request:

{
  "model": "gpt-5.2",
  "input": "Search for the latest Tesla stock price and convert it to EUR",
  "tools": [
    {
      "type": "web_search"
    },
    {
      "type": "function",
      "name": "convert_currency",
      "description": "Convert between currencies",
      "parameters": {
        "type": "object",
        "properties": {
          "amount": { "type": "number" },
          "from": { "type": "string" },
          "to": { "type": "string" }
        },
        "required": ["amount", "from", "to"]
      }
    }
  ]
}

Provider Limitations

Google Vertex AI (Gemini) and Mistral models do not support using web search and function tools together in the same request. When both are provided, function tool calling takes priority and web search is ignored. To use web search with these providers, use tool_choice to explicitly select it:

{
  "model": "gemini-2.5-pro",
  "input": "What happened in the news today?",
  "tools": [
    { "type": "web_search" },
    {
      "type": "function",
      "name": "convert_currency",
      "description": "Convert between currencies",
      "parameters": {
        "type": "object",
        "properties": {
          "amount": { "type": "number" },
          "from": { "type": "string" },
          "to": { "type": "string" }
        },
        "required": ["amount", "from", "to"]
      }
    }
  ],
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [{ "type": "web_search" }]
  }
}

Provider Support

Web search is supported across multiple providers:

Provider	Supported	Notes
OpenAI	Yes	GPT-4o, GPT-4.1, GPT-5 family
Anthropic	Yes	Claude Sonnet, Opus, Haiku models
xAI	Yes	Grok-4 family
Google Vertex AI	Yes	Gemini models. No `search_context_size`/`filters` support. Cannot combine with function tools
Mistral	Yes	Mistral Small, Medium, Magistral. No `search_context_size`/`filters` support. Cannot combine with function tools

The table above reflects native support only. Through the Exa engine, web search also works on models with no native support, as long as they support function tool calling.

Check specific model support using the List Models endpoint.

Tool Calling

Define custom function tools

Create Response

Main API endpoint reference

API Documentation

Responses

Chat Completions (Beta)

Messages (Beta)

Models

Utilities

Features

Reference

Overview

Prerequisites

Quick Start

Tool Parameters

Search Context Size

Domain Filtering

User Location

Search engines

Exa engine

Pricing

Response Format

Combining with Function Tools

Provider Limitations

Provider Support

Tool Calling

Create Response

​Overview

​Prerequisites

​Quick Start

​Tool Parameters

​Search Context Size

​Domain Filtering

​User Location

​Search engines

​Exa engine

​Pricing

​Response Format

​Combining with Function Tools

​Provider Limitations

​Provider Support

​Related Pages

Tool Calling

Create Response

Overview

Prerequisites

Quick Start

Tool Parameters

Search Context Size

Domain Filtering

User Location

Search engines

Exa engine

Pricing

Response Format

Combining with Function Tools

Provider Limitations

Provider Support

Related Pages