Web search - ClearMaas

Two paths to web search through ClearMaas:

Search-preview models �?call a search variant directly via /v1/chat/completions
Tools / options on a regular model �?pass web_search_options (Chat) or tools: [{"type": "web_search"}] (Responses)

Search-preview models (OpenAI)

OpenAI publishes search-preview variants for several models �?for example openai/gpt-4o-search-preview and openai/gpt-5-search-api. Pick one of these as model on /v1/chat/completions and the upstream handles search server-side. Call /v1/models for the live catalog.

web_search_options (Chat Completions)

curl https://api.clearmaas.com/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -d '{
    "model": "openai/gpt-4o-search-preview",
    "messages": [{"role": "user", "content": "What changed in OpenAI pricing this week?"}],
    "web_search_options": {"search_context_size": "medium"}
  }'

search_context_size: low / medium / high. Controls search depth (per-call price for web_search is the same regardless of size).

Tools (Responses API)

/v1/responses accepts tools: [{"type": "web_search"}] on both OpenAI models and any Grok model �?xAI’s Agent Tools surface lives at the same endpoint.

# OpenAI
curl https://api.clearmaas.com/v1/responses \
  -H "Authorization: Bearer sk-..." \
  -d '{
    "model": "openai/gpt-5",
    "input": "What changed in OpenAI pricing this week?",
    "tools": [{"type": "web_search"}]
  }'

# Grok (xAI Agent Tools)
curl https://api.clearmaas.com/v1/responses \
  -H "Authorization: Bearer sk-..." \
  -d '{
    "model": "grok/grok-4-fast-reasoning",
    "input": "What changed in xAI pricing this week?",
    "tools": [{"type": "web_search"}]
  }'

Each web_search_call the upstream emits is counted for billing �?see Operations / Billing & Usage.

Cross-provider support

Web search reaches every provider that exposes it; only the entry point differs:

Provider	Web search	How
OpenAI	Yes	Search-preview models, or pass `web_search` tool to `/v1/responses`
xAI Grok	Yes	Call `/v1/responses` with `tools: [{"type": "web_search"}]` and any Grok model �?xAI’s Agent Tools API. (xAI deprecated the legacy `search_parameters` on chat completions on 2026-01-12; the old `*-search` model-name variants no longer work.)
Anthropic	Yes	Pass `web_search_options` on a Chat Completions request �?translated to Anthropic’s native `web_search` server-tool. `search_context_size` (low/medium/high) maps to `max_uses`; `user_location.approximate` maps to Anthropic’s `user_location`.
Gemini	Yes	Pass a function tool named `googleSearch` (see below) �?translated to Gemini’s native `GoogleSearch` grounding tool.
DeepSeek	No	DeepSeek API does not expose web search.

Gemini grounding via `googleSearch`

For Gemini models, ClearMaas’s translation layer recognizes a magic function name googleSearch and turns it into Gemini’s native GoogleSearch grounding tool. Send it like any other OpenAI-style function tool:

curl https://api.clearmaas.com/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [{"role":"user","content":"What changed in Gemini pricing this week?"}],
    "tools": [{"type":"function","function":{"name":"googleSearch"}}]
  }'

resp = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{"role": "user", "content": "What changed in Gemini pricing this week?"}],
    tools=[{"type": "function", "function": {"name": "googleSearch"}}],
)

The grounding metadata Gemini returns (webSearchQueries, etc.) is captured by the gateway for billing and surfaced through standard chat-completion fields. Two related magic function names are recognized on the same code path:

codeExecution �?enables Gemini’s native code-execution tool
urlContext �?enables Gemini’s URL-context tool

Or go native

If you’re already on Gemini’s native protocol via /v1beta/, pass googleSearch directly in Gemini shape �?no magic-name translation needed:

curl "https://api.clearmaas.com/v1beta/models/google/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"What changed in Gemini pricing this week?"}]}],
    "tools": [{"googleSearch": {}}]
  }'

{"codeExecution": {}} and {"urlContext": {}} work the same way on the native path. See Native Formats / Gemini.

Billing

web_search and web_search_preview are tracked as built-in tool calls. They have different pricing tiers �?see Operations / Billing & Usage for the breakdown.

​Search-preview models (OpenAI)

​web_search_options (Chat Completions)

​Tools (Responses API)

​Cross-provider support

​Gemini grounding via googleSearch

​Or go native

​Billing