For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
Give your Claude-powered applications real-time web search by registering Parallel Search as a tool. This guide shows how to define Parallel Search using Anthropic’s Messages API and handle the tool-call loop.
.md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. On /v1/search, search_queries is required (at least one short keyword query), and max_results, source_policy and fetch_policy go inside advanced_settings; sending only objective, or sending those fields at the top level, returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.If you are evaluating Parallel Search or comparing it with other search APIs, read How to Eval Parallel Search before you build the harness, especially its Common pitfalls section. The most common mistake is sending the raw question as both objective and the only entry in search_queries. Write a goal-style objective and 1-3 short keyword queries instead.Overview
Anthropic’s tool use lets Claude emit a structuredtool_use block when it wants to call a function you’ve defined. Your application executes the function and returns a tool_result block in a follow-up user message. By registering Parallel Search as a tool, Claude can:
- Search the web for current information
- Access real-time news, research, and facts
- Cite sources with URLs in responses
The Anthropic SDKs also ship a higher-level Tool Runner helper (currently in beta) that runs the loop for you. The example below uses the manual loop so the request/response shapes are explicit; once you understand them, switch to Tool Runner for less boilerplate.
Prerequisites
- Get your Parallel API key from Platform
- Get your Anthropic API key from Anthropic Console
- Install the required SDKs:
Define the Search Tool
Anthropic tool definitions usename, description, and input_schema (no outer function wrapper, and the schema field is input_schema rather than OpenAI’s parameters). See Search Tool Definition for a framework-agnostic, copy-paste-ready version.
Add
"strict": true to the tool definition to enable strict tool use, which guarantees that Claude’s tool inputs conform to your schema exactly.Implement the Search Function
Create a function that calls the Parallel Search API when Claude requests it:Process Tool Calls
Claude returns one or moretool_use blocks inside response.content whenever stop_reason == "tool_use". Execute each call and reply with a user message whose content is a list of tool_result blocks:
Anthropic requires that
tool_result blocks come first in the content array of the user message that follows a tool_use response — any free-form text must come after them.Complete Example
End-to-end: a loop that lets Claude callsearch_web until it has enough information to answer.
Tool Parameters
This example uses the default
advanced mode, which prioritizes result quality for tool use. For lower-latency responses, consider "turbo" (p50 ~200ms) or "fast" (~700ms). To switch, set the search mode to "turbo" inside your search_web handler. The tool schema the model sees stays unchanged. See Search Modes.