How Server-Sent Events Power Claude's Streaming Responses

When you call the Claude Messages API without streaming, you send a request and wait.

Nothing comes back until the entire response is finished generating.

For a long answer, that wait can be several seconds of a blank screen.

Streaming changes the delivery mechanism, not the content: instead of one big response at the end, Claude sends the same response as a sequence of small, typed events over a single open connection, as the words are generated.

Understanding the transport underneath streaming - Server-Sent Events - and the shape of the events it carries is the foundation for everything else in this section, from printing tokens as they arrive to building a live chat UI to streaming tool calls.

Summary

• Core Idea: Claude's streaming API sends the response as an ordered sequence of typed SSE events over one HTTP connection, rather than as a single JSON blob at the end.
• Why It Matters: It lets an application start rendering output the moment the first tokens exist, instead of blocking the user interface until generation completes.
• Key Concepts: Server-Sent Events, event stream, message_start, content_block_delta, text_delta, message_delta, message_stop.
• When to Use: Any user-facing surface where perceived latency matters - chat UIs, coding assistants, live document generation, and any long response the user is actively watching.
• Limitations / Trade-offs: Streaming adds client-side complexity (partial state, error handling, reconnects) and is not compatible with some caching or batch-processing patterns that want the full response as a unit.
• Related Topics: the Messages API request/response model, tool use, extended thinking, the Python SDK's streaming helper.

Foundations

Server-Sent Events (SSE) is a long-standing web standard for one-directional, server-to-client streaming over plain HTTP.

A client opens a normal HTTP request, but instead of the server sending one response and closing the connection, the server keeps the connection open and writes a sequence of small text frames to it over time.

Each frame is prefixed with data: and separated by blank lines - it is deliberately simple, simpler than WebSockets, because it only needs to flow in one direction: server to client.

Claude's Messages API uses this exact mechanism when you request stream=true (or use the SDK's streaming helper).

Instead of one HTTP response body containing the finished message, the connection stays open and the server writes a series of events, each one a small JSON object describing one incremental piece of the response.

A useful analogy: a non-streaming response is like waiting for a whole letter to be printed and then handed to you.

A streaming response is like watching someone type that same letter in front of you, one line at a time, through a window that tells you exactly what kind of thing just got typed - a heading, a sentence, a signature.

The event types are what make that useful: each one names precisely what changed, so client code never has to guess.

import anthropic
 
client = anthropic.Anthropic()
 
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain SSE in one paragraph."}],
) as stream:
    for event in stream:
        print(event.type)  # message_start, content_block_delta, ..., message_stop

That loop is the shape every streaming consumer takes: open a stream, receive a sequence of typed events, and react to each type differently.

Mechanics & Interactions

The event sequence for a typical text response follows a fixed skeleton:

message_start
  content_block_start   (index 0, type: text)
    content_block_delta (text_delta, "Hello")
    content_block_delta (text_delta, " there")
    content_block_delta (text_delta, "!")
  content_block_stop    (index 0)
message_delta           (stop_reason, usage totals)
message_stop

message_start arrives first and carries the message's metadata shell - its id, model, and initial (near-zero) usage - before any content exists yet.

Between that and message_stop, the response is built out of one or more content blocks, each opened with content_block_start and closed with content_block_stop.

A single response can contain multiple content blocks in sequence - for example a thinking block followed by a text block, or a text block followed by a tool_use block - and each is identified by its index so a client can track several blocks' partial state independently.

The actual token-by-token output arrives as content_block_delta events nested inside a block's start/stop pair.

For a text block, the delta's delta.type is text_delta and its delta.text is the next fragment of text - concatenating every text_delta for a block, in order, reconstructs that block's full text.

content_block_delta is a generic envelope, though - the delta.type inside it varies by what kind of block is streaming: text_delta for prose, input_json_delta for a tool call's arguments, and thinking_delta for extended thinking, each carrying a different partial payload that gets assembled differently.

message_delta arrives once, near the end, and carries message-level fields that were not known until generation finished - stop_reason (why the model stopped) and running token usage totals.

message_stop is the final event and signals that the stream is complete; no more events will follow for this response.

A common reasoning mistake is expecting one content_block_delta to equal one token, or one text_delta to be a clean word boundary.

Neither is guaranteed - a delta can be a partial word, several tokens, or even split mid-character-sequence for multibyte text - so client code should treat deltas as opaque fragments to concatenate, never as units to parse individually.

Advanced Considerations & Applications

The event model scales to Claude's more advanced capabilities without changing its shape, which is what makes it composable.

A tool call streams its input as a JSON string built up incrementally across many input_json_delta events - the partial string is not valid JSON until the block closes, so a client must buffer every delta for that block and only attempt to parse once content_block_stop fires for it. See Handling Partial JSON During Streamed Tool Calls for the accumulation pattern.

Extended thinking, when enabled, streams its reasoning as a separate content block using thinking_delta events, ahead of the text block - a UI can render that block distinctly (e.g., a collapsed "reasoning" panel) rather than mixing it into the answer text. See Streaming Extended Thinking Blocks to the Frontend.

Because tool calls stream through the same event types as text, a client can watch one stream for both: render text as it arrives, and the moment a content_block_start reports type: "tool_use", know it is time to accumulate arguments instead of displaying them - this is the basis of combining streaming with the tool-use loop.

At the transport level, SSE rides over the same HTTP connection as any other API call, so it inherits ordinary network failure modes - proxies that buffer output, load balancers with idle timeouts, and connections that simply drop mid-response.

Production code has to treat the stream as unreliable: buffer what has arrived, detect a drop, and decide whether to resume or restart the request. See Streaming Best Practices for the concrete patterns.

Common Misconceptions

• "Each SSE event is one token." In practice a text_delta can span multiple tokens or be a sub-token fragment - never assume a fixed granularity, always concatenate.
• "The stream sends the whole message and I filter it client-side." The server does the incremental generation; the client only ever sees what has been generated so far, not the full message in advance.
• "content_block_delta always means text." It's a generic envelope - its inner delta.type determines whether it's text_delta, input_json_delta, or thinking_delta.
• "Streaming is a different API." It's the same Messages API and the same request body, with stream=true (or the SDK's streaming helper) changing only how the response is delivered.
• "A dropped connection mid-stream still gives you a valid partial message." A drop can happen at any byte boundary; the client must handle an incomplete block gracefully, not assume it received a clean prefix.

FAQs

Related

• Streaming Responses Basics - the first runnable example of consuming this event stream.
• Streaming Event Types Reference - a lookup table for every event type and its fields.
• Handling Partial JSON During Streamed Tool Calls - accumulating input_json_delta safely.
• Streaming Extended Thinking Blocks to the Frontend - handling thinking_delta.
• Streaming Responses with the Python SDK - the SDK's streaming helper in more depth.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.