Parallel research

parallel:research gives any chat model a research assistant. The model writes one complete question. Parallel searches and reads the live web itself, and the model gets back a finished answer with its sources, not a list of search results to read through. You add the tool to tools (or send one header), the model decides when to call it, the gateway runs each call, and you get one finished answer. It works alongside tako:search, parallel:search and parallel:extract in the same request. This page takes you from a key to a first answer; Server tools is the full reference.

Quickstart

1. Get a key

Sign in and create a key at API keys. Use an organization key: each research call is billed to an organization.

2. Add paid credit

Add credit in Billing. Before each call runs, your balance must cover its price ($0.01 at low effort, $0.05 at medium), on top of the model's own turns.

3. Export the key

export TM_API_KEY=tm_vk_...

4. Send a first request

curl https://api.routerplus.com/v1/chat/completions \
  -H "Authorization: Bearer $TM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Which G7 country has the highest corporate income tax rate in 2026, and what is it?"}],
    "tools": [{"type": "parallel:research", "parameters": {"max_uses": 1, "max_effort": "medium"}}]
  }'

The same with the header instead of a tools entry (default parameters):

curl https://api.routerplus.com/v1/chat/completions \
  -H "Authorization: Bearer $TM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-tm-tools: parallel:research" \
  -d '{"model": "claude-haiku-4-5", "messages": [{"role": "user", "content": "Which RFC defines HTTP semantics?"}]}'

The header works on /v1/chat/completions, /v1/messages and /v1/responses, and takes parallel:research alone or with the other server tools, comma-separated, for example x-tm-tools: parallel:search, parallel:research. In Claude Code set "ANTHROPIC_CUSTOM_HEADERS": "x-tm-tools: parallel:research"; in Codex, http_headers = { "x-tm-tools" = "parallel:research" } (see Server tools). We have not yet run it live with either harness.

Parameters

Research calls are slow, so a request has a research budget: max_uses times the per-call timeout of max_effort (below) may not pass 100 seconds. That allows up to 3 calls at "low" and up to 2 at "medium". max_effort: "high" is not available on this gateway: in our probes high took 65 to 71 seconds a call, too close to the request's 150-second limit.

Any other field is a 400 invalid_request that names it. So is a value out of range, a max_uses over the budget, a second parallel:research entry, or a function of your own named parallel_research. That includes the Parallel Responses fields the gateway never sends: tools, data_sources, mcp, previous_response_id, instructions, stream and background. Nothing is called or billed then.

Cost

Parallel's list price for each call, by the effort it ran at, with no markup:

Each call holds the price of the effort the model asked for before it runs, and is charged the price of the effort Parallel says it ran at, never more than it held. A call that fails, times out or is stopped is not billed. The model's turns are billed as ordinary chat requests, at the model's price.

The model picks the effort, so max_effort is your cost cap. With no parameters (one call, up to medium) a request costs at most $0.05 in research, plus the model's turns. The most any request can cost in research is $0.10 (2 calls at medium) or $0.03 (3 calls at low).

On the answer, usage.cost is the turns plus every call, in USD, and usage.server_tool_use.parallel_research_requests counts the calls billed. The x-tm-server-tools header says the same, for example parallel_research=1. In GET /v1/usage & /v1/generation each call is its own attempt: provider parallel, model parallel:research, web_search_requests: 1 (one research call), and server_tool_fee_usd: 0.01 or 0.05.

Time

Each call has its own timeout: 30 seconds at low and 50 seconds at medium. In our probes (10 calls at low and 8 at medium, from one machine of ours), low answered in about 1 second (2.3 seconds at the slowest) and medium in about 6 seconds (16.5 seconds at the slowest). The whole request, every model turn and every call, has 150 seconds when the answer is streamed and 110 seconds when it is not, after which it ends (a 504 when not streamed). A call that times out gives the model {"error":"parallel_research failed"}, is not billed, and the model goes on.

While the model researches, nothing arrives but the finished answer. A non-streamed request returns nothing until it is done, within 110 seconds: Cloudflare cuts a silent response at 125 seconds, so the gateway ends it first. A streamed answer starts at once, on every endpoint, and sends only keep-alives until then. Two medium calls can take most of 110 seconds, so stream research requests, and set your client's timeout above 150 seconds. See Server tools.

What the model sees

One function, parallel_research(question, effort):

• question: one complete, self-contained question. Parallel sees nothing else of the conversation, so the question must carry every name, date and detail it needs. It is trimmed and cut at 4,000 characters.
• effort: "low" or "medium", up to max_effort. Without it the call runs at "low".

The description tells the model to prefer one thorough call to several narrow ones, and to use "medium" only for multi-hop questions that need several sources combined. An effort above max_effort, or no question, gives the model an error result. Nothing is called or billed then.

The result is JSON: answer (the text), citations (url and title of each source: at most 20, each URL once, http(s) only) and effort (the effort it ran at). Nothing else from Parallel's reply reaches the model or you: not its id, usage or metadata, and not the searches it ran. The result is at most 16 KB: citations are dropped from the end first, then the answer is shortened. At low effort Parallel often answers without searching, and then there are no citations (9 of 10 low answers in our probes).

Read the answer

• /v1/chat/completions: an ordinary chat.completion.
• /v1/messages: each call is a server_tool_use block (name: "parallel_research", input {question, effort}), then a parallel_research_tool_result block, before the answer.
• /v1/responses: each call is a parallel_research_call item, with action: {type: "research", question, effort}.

Send those blocks or items back in the history and the gateway replays them as the calls they stand for.

Data

With parallel:research, the question the model writes is sent to Parallel, a third party in the United States, with our key. Your messages as such, your key and your organization are not sent, but the model writes the question from your conversation, so it can quote or paraphrase what you wrote. Parallel's documentation says it stores every Responses API answer on its side (store: false does not change that), except on zero-data-retention accounts; zero data retention is an Enterprise plan, and our account is not on it. Under Parallel's standard terms it may use inputs and outputs, not linked to any individual, to improve its models; until our account terms with Parallel are settled, assume it does. Our process log and billing ledger keep only the count, status, time and fee of each call, never the question or the answer. The model's turns are ordinary chat requests, so the request log keeps them under its usual rules, with the question (in the model's call) and the answer (in the tool message). See Data policy.

Troubleshooting

• 400 server_tool_unsupported, "parallel:research is not enabled on this gateway": the gateway you called does not serve parallel:research (a gateway can serve parallel:search and parallel:extract and not this tool), so nothing was researched or billed. Ask support to turn it on, or remove it from tools or the header to send the request without it.
• 400 naming max_uses: the research budget. Lower max_uses or max_effort.
• 400 naming max_effort, "high" is not available: use "low" or "medium".
• 503 "turned on but not configured": parallel:research is turned on for the gateway you called, but our Parallel key is not in place yet. Ask support; retrying will not help until the key is configured.
• 429 insufficient_quota, "credit balance too low for this request": your balance or a monthly spend cap does not cover the call's price ($0.01 at low, $0.05 at medium) on top of the turns. Nothing was researched. Add credit, or lower max_effort.
• The model's result is an error instead of an answer. The model gets one of these, and none is billed:
  • {"error":"parallel_research failed"}: Parallel refused, timed out, or answered without a finished answer.
  • {"error":"parallel_research limit for this request reached; continue without it"}: the call was over max_uses.
  • {"error":"parallel_research rate limit reached; continue without it"}: over 60 Parallel calls a minute for your organization (every Parallel tool together).
  • {"error":"parallel_research effort must be \"low\" or \"medium\"; nothing was researched"}: the model asked for an effort above max_effort (the allowed efforts are listed).
  • {"error":"parallel_research needs question: one complete, self-contained question"}: the model sent no question.
• 504 after 110 seconds: the limit of a request that is not streamed (a streamed one has 150 seconds). Send "stream": true, or use fewer calls or a lower effort.

Where next

• Server tools: the full reference, and every server tool together
• Parallel tools: web search, page reading, images, places and decisions, from $0.001 a call
• Pricing & billing: the billing math and usage.cost
• Data policy: what is stored and by whom