Skip to main content
POST
Model-grounded web search (Anthropic).
Ask a question and get an answer that Claude wrote after searching the live web. Send a normal Messages request — a messages array plus max_tokens — and the endpoint injects a fixed, server-pinned model and the web_search tool for you; you cannot override the model or add tools, which keeps cost bounded. Claude decides when to search (up to max_uses searches, default 5), reads the results, and answers with inline citations. The response is a standard Anthropic Messages object: content[] contains server_tool_use (the queries issued), web_search_tool_result (the sources found) and text blocks (the answer with citations), and usage.server_tool_use.web_search_requests reports how many searches were billed. Billing is pay-as-you-go at exact cost: web_search_requests × $0.01 plus the model’s own token cost, with no markup; a failed search (HTTP 200 web_search_tool_result_error) is not billed. Use this when you want a written, cited answer grounded in current web content — for open-web research that returns ranked links and page text in one call use post_tavily_search instead, and for the OpenAI-model equivalent see post_openai_websearch_search.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
messages
object[]
required

Conversation messages, same format as the Anthropic Messages API. The user turn holds your question.

Example:
max_tokens
integer
default:1024
required

Maximum number of tokens to generate in the answer. Required by the upstream Messages API.

Example:

1024

system
string

Optional system prompt to steer the answer's tone or format.

Response

200 - application/json

A standard Anthropic Messages response. content[] interleaves the searches performed and the cited answer; usage.server_tool_use.web_search_requests is the billed search count.

id
string
type
string
Example:

"message"

role
string
Example:

"assistant"

stop_reason
string
Example:

"end_turn"

content
object[]

Ordered blocks: server_tool_use (search queries), web_search_tool_result (sources), and text (the cited answer).

usage
object