Claude Code Request Build

Claude Code Request Build

Each time the model must answer, Claude Code builds one request to the Messages API. The request holds the tool list, the system prompt, and the whole conversation so far. What you change in it decides what the cache can reuse, so it decides speed and cost.

Example

You switch models in the middle of a task with /model. The next request has no cache hits, because each model has its own cache. Pick the model at the start of a session to avoid this.

Parts of a Request

The API reads the parts in this order. A change in an early part makes the later parts miss the cache. Source: How Claude Code Uses Prompt Caching.

Part	Mark	Content	Changes when
tools	✅	The tool definitions, where MCP tools are deferred by default so that only their names go in.	The set of loaded tools changes.
system	✅	The attribution line, the identity line, and the system prompt.	The model, the output style, or the prompt flags change.
messages	✅	The first user message with project context (CLAUDE.md, auto memory, unscoped rules), then the conversation.	Every turn.

Project context changes at session start, at /clear, and at /compact.

Body Fields

The field list comes from the docs and from an api-request line that 2.1.303 wrote to a local transcript.

Field	Mark	Content
model	✅	The model ID.
max_tokens	✅	The output limit, which CLAUDE_CODE_MAX_OUTPUT_TOKENS can change up to the model cap.
thinking	✅	The thinking mode, such as {"type": "adaptive"}.
output_config	✅	The effort level, the format of structured output, and task_budget (Gateway Compatibility Guide).
context_management	✅	Edits that clear old thinking or old tool results.
safeguards	🔍	A list of safety checks, such as dangerous_tool_use, with the context that the check needs.
system	✅	An array of text blocks with cache_control.
tools	✅	An array of tool definitions.
messages	✅	The conversation, where an entry with role: "system" can join in the middle.
anthropic-beta header	✅	The list of beta values (see API Betas).
CLAUDE_CODE_EXTRA_BODY	✅	An env var that adds fields to the body.

The transcript line api-request records the request, and the lines api-request-shape and api-request-blob store parts of it once. All three are 🔍 (see Sessions Transcript).

System Blocks and Cache Markers

An observed request had three system blocks and three cache markers.

Position	Mark	Marker
system[0] (attribution line)	🔍	No marker.
system[1] (identity line)	🔍	ephemeral, ttl: 1h, scope: global.
system[2] (system prompt)	🔍	ephemeral, ttl: 1h.
Last block of the last message	🔍	ephemeral, ttl: 1h.

Claude Code also marks the block of system context in the middle of a conversation, such as file-change notices, on every provider. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS turns this off. If a gateway rejects the marker with a 400, Claude Code moves it to the last message and keeps it there. Source: How Claude Code Uses Prompt Caching.

Cache Lifetime

Source: How Claude Code Uses Prompt Caching and Environment Variables.

Item	Mark	Effect
Main conversation	✅	The cache lasts one hour on a Claude subscription within plan usage, and five minutes otherwise.
Subagents, workflows, forks, compaction, and titles	✅	The cache lasts five minutes, except for some helper requests that the server sets.
promptCacheTtl, CLAUDE_CODE_PROMPT_CACHE_TTL	✅	Sets 5m or 1h for the main conversation.
subagentPromptCacheTtl, CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL	✅	Sets 5m or 1h for everything else.
ENABLE_PROMPT_CACHING_1H	✅	Asks for one hour in both groups.
FORCE_PROMPT_CACHING_5M	✅	Forces five minutes and wins over the other items.
DISABLE_PROMPT_CACHING	✅	Turns caching off. The suffixes _HAIKU, _SONNET, _OPUS, and _FABLE turn it off for one model family.
DISABLE_PROMPT_CACHING_MYTHOS	🔍	Turns caching off for the Mythos models.
CLAUDE_CODE_MESSAGES_PROMPT_CACHE_TTL	🔍	Appears in the env schema, and no source states what it does.

The cache is per machine and per folder, because the prompt holds memory paths and the working directory.

What Breaks the Cache

Source: How Claude Code Uses Prompt Caching.

Action	Mark	Effect
Switch model	✅	Full miss, and /model asks first while the cache is warm.
Change effort	✅	Full miss on most models, but Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.1 keep the cache.
Turn on fast mode	✅	One miss, because a header joins the cache key.
Add or remove MCP tools that are not deferred	✅	A miss, while deferred tools keep the first tool list for the conversation.
Deny a whole tool	✅	A miss, because its definition leaves the list.
Run /compact	✅	A new prefix starts.
Upgrade Claude Code	✅	A miss.
Enable a plugin with skills, agents, or hooks	✅	No miss, because the content is appended.

Per-Turn Values

Some models can take their effort level and the current time with each message. Claude Code then sends them in a system entry of the message, with the betas per-turn-control-2026-07-01 and timing-2026-09-09. These values are 🔍 (see Models Capabilities).

Facts from Probes

A local stub of the Messages API showed these facts (Probes).

• A model name with the [1m] suffix adds the context-1m-2025-08-07 beta. Without the suffix it is never sent.
• The call to /v1/messages/cache_touch needs a subscriber login and the cache-keepalive-2026-09-03 beta. It repeats every 30 seconds (10 to 120), with the body {"request_id": ...}.

See Also

• System Prompt
• API Endpoints
• API Betas
• Context and Compaction
• Turn Pipeline
• Probes