How can a paused Claude API search turn be continued?

Definition: pause_turn is a Claude Messages API stop reason for a long-running server-tool search turn. To continue, the client sends a new request containing the paused assistant message unchanged, including the content blocks returned by the API.

Key facts

• Anthropic's web search tool documentation says that a long-running search turn can return stop_reason: "pause_turn" and that the paused assistant message must be sent back unchanged in a new request.
• Search results contain encrypted_content, which the client passes back in multi-turn conversations. Missing or modified encrypted_content causes a 400 validation error.
• Anthropic's stop reasons documentation says that pause_turn occurs when a server-tool loop reaches its iteration limit, with a default of 10 iterations per request.
• The paused response may contain a server_tool_use block without a matching result block. Sending the response back as-is lets Claude finish processing.
• A parallel client tool call follows the tool_use path: the client returns tool_result blocks, and the API runs the search in the next request.

What does pause_turn mean?

The Messages API returns a stop_reason field with the response. Anthropic's stop reasons documentation describes pause_turn as the point at which the server-side sampling loop reaches its iteration limit while executing a server tool such as web search. Its documented default is 10 iterations per request. A paused response can therefore be an intermediate server-tool state rather than the end of the search turn.

The same documentation separates this state from a client tool call. If Claude calls web search and a client tool in the same group of parallel tool calls, the web search waits, stop_reason is tool_use, and the next request carries the client tool results. The pause_turn path carries the assistant response itself.

What content must the next request preserve?

Anthropic's web search documentation requires the assistant's content blocks to be replayed exactly as received. This includes each search result's encrypted_content. Anthropic says that the API decrypts this field on a later turn to restore the search results in Claude's context. A client therefore needs to retain the complete assistant content array, including block order, block types, search result fields and encrypted values.

{
  "messages": [
    {"role": "user", "content": "Search for latest AI news"},
    {"role": "assistant", "content": response.content}
  ]
}

The stop reasons example uses the same sequence: inspect response.stop_reason, append an assistant message whose content is response.content, then make another Messages API request. The next request keeps the tools available so the server-side work can continue.

How can an API client check the branch?

A client checks stop_reason before deciding what to append. For pause_turn, the stop reasons documentation shows the assistant response being appended to the existing messages array and a new request being made. The web search guide describes the same action as sending the paused assistant message back unchanged.

For tool_use, the client executes its own tool and returns the resulting tool_result blocks. The search guide says that the API then runs the search in the next request. These paths require different preserved data: pause_turn preserves the assistant response, while tool_use returns the client tool results.

The web search response also carries citations for sources drawn from search results. Search result locations include the source URL, title, encrypted index and cited text. Those fields belong to the response content that a client handling later search turns must preserve when the API returns them.

Related terms

• Claude web search
• Why must encrypted_content be preserved between Claude search turns?
• What happens when Claude exceeds the configured search limit?
• Can a Claude search tool failure arrive in a successful HTTP response?

FAQ

What does unchanged mean when you continue a paused turn?

You send the assistant content blocks back exactly as the API returned them. For search results, this includes each result's encrypted_content and its original value.

Does pause_turn mean that the search failed?

The documented condition is a server-side sampling loop reaching its iteration limit. You continue by sending the assistant response back as-is so Claude can finish processing.

What should you send after a client tool call?

You return the client tool's tool_result blocks when the response has stop_reason: "tool_use". The API then runs the waiting web search in the next request.

Sources

1. Anthropic, "Web search tool", null
2. Anthropic, "Stop reasons and fallback", null

---

Check how a page reads to answer engines. Open the GEO score analyzer