Big Picture 5: The Response and stop_reason
The model has finished writing and the response comes back. It holds different content blocks, plus a stop_reason that says why the model stopped. That stop_reason decides what happens next.
- 1.Response arrives (one JSON, or SSE events when streaming)
- 2.Content blocks: thinking, text, tool_use
- 3.stop_reason says why the model stopped
- 4.end_turn goes to Output (Big Picture 7); tool_use goes to the Tool loop (Big Picture 6)
- 5.max_tokens, pause_turn, refusal need special handling
- 6.usage: input, output, cache read/write tokens become the bill
Response shape
- Non-stream vs stream: without streaming, one complete JSON arrives at once. With streaming, SSE events arrive: message_start, then deltas in pieces, then message_stop (see Big Picture 12).
- thinking: the model's reasoning. It may be shown as a summary or stay hidden.
- text: the actual answer.
- tool_use: a tool name plus its JSON input. It is the model saying: run this tool with this input.
stop_reason: why the model stopped
- stop_reason: the key question. It decides the next path.
- end_turn: the work is done, so the answer goes to the user (Big Picture 7).
- tool_use: the model needs a tool, so the tool loop runs (Big Picture 6).
- max_tokens: the answer got cut off. Raise the limit or send continue.
- pause_turn: a server tool is running long. Send the response back as it is.
- refusal: safety stopped it. Use a fallback or rephrase the question.
- usage: input tokens, output tokens, and cache read / write tokens. This is what your bill is made from.
Interview angle: always branch on stop_reason, never assume a response is final text. Big Picture 12 covers how to handle each failure path.