Streaming

What Is Streaming?

By default the Claude API generates a complete response before returning it. The user waits, sees nothing, then receives everything at once. Streaming changes this. Claude sends the response in chunks as it generates — word by word, exactly like you see responses appear in Claude.ai. The user sees text immediately and reads along as it arrives. One field enables it:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Explain what streaming is."
    }
  ]
}

Why Streaming Matters

The difference between streaming and non-streaming is felt immediately by users — especially for longer responses.

Without Streaming	With Streaming
Blank screen until fully generated	Text appears immediately
All-or-nothing delivery	Progressive, readable delivery
Poor experience for long responses	Natural conversational feel
Simple to implement	Slightly more complex to implement

For any application displaying Claude’s responses directly to users — chat interfaces, writing tools, coding assistants — streaming is the right choice.

How Server-Sent Events Work

Streaming responses use Server-Sent Events (SSE) — a standard web protocol for pushing a stream of data from server to client over a single HTTP connection. Instead of one JSON response, you receive a sequence of events. Each event has two parts:

event: <event_type>
data: <json_payload>

Your application reads events as they arrive and processes each one based on its type.

The Complete Event Sequence

Here is the full streaming response from a real tested request — every event in order:

event: message_start
data: {"type":"message_start","message":{"id":"msg_011Cd8D8...","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","stop_reason":null,"usage":{"input_tokens":19,"output_tokens":1,"service_tier":"standard","inference_geo":"global"}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type":"ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Here"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s counting from one to five:\n\n1, 2, 3, 4, 5\n\n---\n\nStreaming is the continuous delivery of data"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" (such as video, audio, or other content) over the internet in real time,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" allowing users to watch or listen as it arrives rather than waiting for an"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" entire file to download first. Examples include Netflix, Spotify, and YouTube."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":19,"output_tokens":90}}

event: message_stop
data: {"type":"message_stop"}

Breaking Down Each Event

message_start

Opens the stream. Carries the message ID and initial token count.

{
  "type": "message_start",
  "message": {
    "id": "msg_011Cd8D8...",
    "model": "claude-sonnet-4-6",
    "usage": {
      "input_tokens": 19,
      "output_tokens": 1
    }
  }
}

Store the message ID for logging. Input tokens are known here — output tokens are not yet known.

content_block_start

Signals that a content block is opening. For standard text responses there is always one content block.

{
  "type": "content_block_start",
  "index": 0,
  "content_block": {"type": "text", "text": ""}
}

ping

A keepalive signal sent by Anthropic to maintain the connection. Carries no content.

{"type": "ping"}

Never attempt to extract text from a ping event. Always check event.type before processing — a ping has no delta field and will throw errors if you treat it like a content_block_delta.

content_block_delta

The actual text chunks. This is the event your application cares about most.

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "'s counting from one to five:"
  }
}

Extract delta.text from every content_block_delta event and append it to your display. The full response is the concatenation of all these values.

content_block_stop

The content block is complete. No more deltas for this block.

{"type": "content_block_stop", "index": 0}

message_delta

Final metadata. Carries the stop reason and output token count.

{
  "type": "message_delta",
  "delta": {"stop_reason": "end_turn"},
  "usage": {"output_tokens": 90}
}

Check stop_reason here — same values as non-streaming responses. Output tokens are only known at this point.

message_stop

The stream is fully complete. Close the connection.

{"type": "message_stop"}

Processing the Stream

Your implementation needs to handle four cases:

For each incoming event:

"content_block_delta" → extract delta.text → append to display
"message_delta" → check stop_reason → log output tokens
"message_stop" → close the stream connection
"ping" → ignore
anything else → ignore safely

Chunk Size Is Unpredictable

Claude does not stream one word at a time. Chunks vary significantly in size. From the real test above:

Chunk	Size
`"Here"`	1 word
`"'s counting from one to five:\n\n1, 2, 3, 4, 5\n\n---\n\nStreaming is the continuous delivery of data"`	18 words
`" allowing users to watch or listen as it arrives rather than waiting for an"`	15 words

Never assume chunk boundaries align with words, sentences, or paragraphs. Always concatenate and render the full accumulated text.

Token Reporting Across Events

Streaming splits token reporting across two events:

Event	Token Information
`message_start`	`input_tokens` — known before generation begins
`message_delta`	`output_tokens` — only known after generation completes

You cannot calculate the full token cost of a streaming request until the message_delta event arrives. Plan accordingly for real-time cost tracking.

Markdown in Streamed Responses

Claude returns markdown inside streamed chunks. From the real test:

1, 2, 3, 4, 5
\n\n

Streaming is the continuous delivery of data If you display responses in a UI, render markdown progressively as chunks arrive — do not display raw text. Users will see **bold** instead of bold if markdown is not rendered.

Streaming and Tool Use

Streaming and tool use can be combined. When Claude decides to call a tool during a streaming response, it streams the tool use decision in chunks — the content_block_delta events carry input_json_delta types instead of text_delta. This is an advanced pattern used in production agent applications where real-time feedback during tool selection improves the user experience.

When to Use Streaming

Use Case	Streaming?	Reason
Chat interface	✅ Yes	Users see responses immediately
Writing assistant	✅ Yes	Real-time text generation feels natural
Code generation	✅ Yes	Developers read along as code appears
Background processing	❌ No	No user is watching — complexity not worth it
Batch operations	❌ No	Programmatic processing favors complete responses
Structured data extraction	❌ No	Easier to parse a complete JSON response

Streaming API Reference

Interactive playground for testing streaming requests

Tool Use

Combine streaming and tool use for real-time agent applications

Tokens

How token reporting differs between streaming and standard responses

Error Handling

Handle errors that occur mid-stream

Getting Started

Core Concepts

Guides

What Is Streaming?

Why Streaming Matters

How Server-Sent Events Work

The Complete Event Sequence

Breaking Down Each Event

message_start

content_block_start

ping

content_block_delta

content_block_stop

message_delta

message_stop

Processing the Stream

Chunk Size Is Unpredictable

Token Reporting Across Events

Markdown in Streamed Responses

Streaming and Tool Use

When to Use Streaming

Further Reading

Streaming API Reference

Tool Use

Tokens

Error Handling

​What Is Streaming?

​Why Streaming Matters

​How Server-Sent Events Work

​The Complete Event Sequence

​Breaking Down Each Event

​message_start

​content_block_start

​ping

​content_block_delta

​content_block_stop

​message_delta

​message_stop

​Processing the Stream

​Chunk Size Is Unpredictable

​Token Reporting Across Events

​Markdown in Streamed Responses

​Streaming and Tool Use

​When to Use Streaming

​Further Reading

Streaming API Reference

Tool Use

Tokens

Error Handling

What Is Streaming?

Why Streaming Matters

How Server-Sent Events Work

The Complete Event Sequence

Breaking Down Each Event

message_start

content_block_start

ping

content_block_delta

content_block_stop

message_delta

message_stop

Processing the Stream

Chunk Size Is Unpredictable

Token Reporting Across Events

Markdown in Streamed Responses

Streaming and Tool Use

When to Use Streaming

Further Reading