Messages API Request Shape, stop_reason & usage
CoreWork with the Messages API's core request/response mechanics · Difficulty 1/5
Explanation
Anatomy of a Request
The Messages API is the core surface for talking to Claude. A request is a list of messages, each with a role (user or assistant) and content. Alongside messages you supply:
model-- which model to call- `max_tokens` -- required on every request
system-- an optional top-level parameter for the System Prompt- optional
tools,temperature,stream
from anthropic import Anthropic
client = Anthropic() # reads ANTHROPIC_API_KEY from the environment
resp = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
system="You are a concise assistant.",
messages=[{"role": "user", "content": "Summarize this ticket: ..."}],
)
print(resp.content[0].text)
print(resp.usage.input_tokens, resp.usage.output_tokens)Roles Alternate, System Is Not a Message
Conversations are user / assistant turns. Unlike some other chat APIs, the System Prompt is not a message with role: "system" -- it is the separate, top-level system parameter.
stop_reason
Every response reports why generation stopped, and integration code should branch on it:
| stop_reason | Meaning |
|---|---|
end_turn | The model finished naturally |
max_tokens | The response was cut off by the token limit |
stop_sequence | A configured stop sequence was hit |
tool_use | The model wants to call a tool |
usage & Statelessness
Every response reports usage (input_tokens, output_tokens, plus cache read/creation tokens) -- the basis for cost modeling. The API itself is stateless across calls: it keeps no memory of prior turns, so the full conversation must be resent on every request. What gets resent, and how it's curated, is context engineering.
Common exam traps
- Believing the System Prompt is a
role: "system"message -- it is a top-levelsystemparameter in the Messages API. - Forgetting that `max_tokens` is required on every request.
- Assuming the API remembers earlier turns -- multi-turn conversation state is the caller's responsibility, not the API's.
- Ignoring
stop_reasonand assuming every response ends the same way (`end_turn`) rather than branching on it.
Key Takeaways
- A Messages API request needs messages (alternating user/assistant), model, and required max_tokens; system and tools are optional
- The system prompt is a top-level system parameter, not a role: "system" message
- stop_reason (end_turn, max_tokens, stop_sequence, tool_use) tells integration code why generation stopped and what to do next
- usage reports input/output/cache tokens and is the basis for cost modeling
- The API is stateless -- the full conversation must be resent on every call
Glossary Terms
A stop_reason value indicating Claude finished its response naturally without hitting a limit or requesting a tool. In agentic loops, this signals the loop should stop and the final response should be presented to the user.
API parameter that sets the maximum number of tokens Claude will generate in a single response. If generation would exceed this limit it is truncated and `stop_reason` is set to `"max_tokens"`. This is a required parameter — omitting it returns a 400 error.
A field in the Claude API response indicating why the model stopped generating. Values: 'end_turn' (natural completion), 'max_tokens' (hit limit), 'stop_sequence' (hit custom stop), 'tool_use' (wants to call a tool). The primary signal for controlling agentic loops.
An API parameter that provides a list of up to four strings that, when encountered in Claude's output, cause generation to halt immediately. The matched string is stripped from the response. When a stop sequence fires, `stop_reason` is set to `"stop_sequence"`. Useful for enforcing structured output boundaries or workflow step delimiters.
The initial instruction set provided to Claude that defines its behavior, role, constraints, and operational context for an entire conversation. Set via the 'system' parameter in the API. Processed before the user turn and shapes all subsequent responses.
A content block type in Claude's response indicating the model wants to call a specific tool. Contains 'id', 'name', and 'input' fields. The agent must execute the tool and return results in a tool_result content block for the conversation to continue.
Related Concepts