Streaming

Streaming

curl --request POST \
  --url https://api.anthropic.com/v1/messages/streaming \
  --header 'Content-Type: application/json' \
  --header 'anthropic-version: <anthropic-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Count from one to five and briefly explain what streaming is."
    }
  ]
}
'

import requests

url = "https://api.anthropic.com/v1/messages/streaming"

payload = {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {
            "role": "user",
            "content": "Count from one to five and briefly explain what streaming is."
        }
    ]
}
headers = {
    "anthropic-version": "<anthropic-version>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'anthropic-version': '<anthropic-version>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    stream: true,
    messages: [
      {
        role: 'user',
        content: 'Count from one to five and briefly explain what streaming is.'
      }
    ]
  })
};

fetch('https://api.anthropic.com/v1/messages/streaming', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.anthropic.com/v1/messages/streaming",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'claude-sonnet-4-6',
    'max_tokens' => 1024,
    'stream' => true,
    'messages' => [
        [
                'role' => 'user',
                'content' => 'Count from one to five and briefly explain what streaming is.'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "anthropic-version: <anthropic-version>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.anthropic.com/v1/messages/streaming"

	payload := strings.NewReader("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"stream\": true,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Count from one to five and briefly explain what streaming is.\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("anthropic-version", "<anthropic-version>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.anthropic.com/v1/messages/streaming")
  .header("anthropic-version", "<anthropic-version>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"stream\": true,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Count from one to five and briefly explain what streaming is.\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.anthropic.com/v1/messages/streaming")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["anthropic-version"] = '<anthropic-version>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"stream\": true,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Count from one to five and briefly explain what streaming is.\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

"<string>"

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

POST

messages

streaming

Streaming

curl --request POST \
  --url https://api.anthropic.com/v1/messages/streaming \
  --header 'Content-Type: application/json' \
  --header 'anthropic-version: <anthropic-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Count from one to five and briefly explain what streaming is."
    }
  ]
}
'

import requests

url = "https://api.anthropic.com/v1/messages/streaming"

payload = {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {
            "role": "user",
            "content": "Count from one to five and briefly explain what streaming is."
        }
    ]
}
headers = {
    "anthropic-version": "<anthropic-version>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'anthropic-version': '<anthropic-version>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    stream: true,
    messages: [
      {
        role: 'user',
        content: 'Count from one to five and briefly explain what streaming is.'
      }
    ]
  })
};

fetch('https://api.anthropic.com/v1/messages/streaming', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.anthropic.com/v1/messages/streaming",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'claude-sonnet-4-6',
    'max_tokens' => 1024,
    'stream' => true,
    'messages' => [
        [
                'role' => 'user',
                'content' => 'Count from one to five and briefly explain what streaming is.'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "anthropic-version: <anthropic-version>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.anthropic.com/v1/messages/streaming"

	payload := strings.NewReader("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"stream\": true,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Count from one to five and briefly explain what streaming is.\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("anthropic-version", "<anthropic-version>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.anthropic.com/v1/messages/streaming")
  .header("anthropic-version", "<anthropic-version>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"stream\": true,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Count from one to five and briefly explain what streaming is.\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.anthropic.com/v1/messages/streaming")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["anthropic-version"] = '<anthropic-version>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"stream\": true,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Count from one to five and briefly explain what streaming is.\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

"<string>"

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

Overview

By default, the Claude API waits until the full response is generated before returning it. Streaming changes this — Claude sends the response in chunks as it generates, word by word, exactly like you see in Claude.ai. Streaming is enabled by adding a single field to your request:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Count from one to five and briefly explain what streaming is."
    }
  ]
}

Why Use Streaming

Without Streaming	With Streaming
User sees blank screen until response is complete	User sees response appearing immediately
Full response held in memory before delivery	Chunks processed as they arrive
Poor experience for long responses	Natural, conversational feel
One large payload	Multiple small event chunks

Almost every production application that displays Claude responses to end users uses streaming. It is the standard approach for chat interfaces, writing tools, and any application where response time affects user experience.

The Event Lifecycle

Streaming responses are delivered as Server-Sent Events (SSE) — a standard web protocol for pushing data from server to client in real time. Each event has a type and a data field. Here is the complete event sequence from a real tested request:

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}}}

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:"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" 1, 2, 3, 4, 5"}}

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

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

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

Understanding Each Event

Event	What It Means	Action Required
`message_start`	Stream begins — carries message ID and initial input token count	Store the message ID for logging
`content_block_start`	A content block is opening	Prepare to receive text chunks
`ping`	Keepalive signal to maintain the connection	Ignore — carries no content
`content_block_delta`	The actual text chunk — one or more words	Extract `delta.text` and append to display
`content_block_stop`	The content block is complete	Finalize the content block
`message_delta`	Final metadata — stop reason and output token count	Check `stop_reason` and log token usage
`message_stop`	Stream is fully complete	Close the stream connection

Extracting the Text

The text you want lives inside content_block_delta events, specifically in the delta.text field. Everything else is lifecycle metadata. For each incoming event: if event.type === “content_block_delta” → append delta.text to your display if event.type === “message_stop” → close the stream if event.type === “ping” → ignore The full response is the concatenation of all delta.text values across every content_block_delta event.

Always check event.type before extracting data. The ping event carries no delta.text field — attempting to extract it without checking the type first will throw errors in your implementation.

Chunk Size Is Variable

Claude does not stream one word at a time. Chunks vary in size — sometimes a single word, sometimes several sentences. From a real tested response:

Chunk	Text
1	`"Here"`
2	`"'s counting from one to five:\n\n1, 2, 3, 4, 5\n\n---\n\nStreaming is the continuous delivery of data"`
3	`" (such as video, audio, or other content) over the internet in real time,"`
4	`" allowing users to watch or listen as it arrives rather than waiting for an"`
5	`" entire file to download first."`

Never assume chunk boundaries align with word or sentence boundaries. Always concatenate and render the full accumulated text.

Token Reporting in Streaming

Token counts are split across two events because output tokens are not known until generation completes:

Event	Token Field	Value
`message_start`	`input_tokens`	Known upfront
`message_delta`	`output_tokens`	Only known after generation completes

This matters for real-time cost tracking — you cannot calculate the full cost of a streaming request until the message_delta event arrives at the end of the stream.

Markdown in Streaming Responses

Claude returns markdown formatting inside streamed text chunks. From a real tested response:

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

Streaming is the continuous delivery of data If you are displaying streamed responses in a UI, render markdown.. do not display raw text. Users will see **bold** instead of bold if markdown is not rendered.

When Not to Use Streaming

Streaming adds implementation complexity. It is only worth it when real-time display matters:

Use Case	Streaming?
Chat interface displaying responses to users	✅ Yes
Writing tool showing text as it generates	✅ Yes
Background processing not shown to users	❌ No
Batch operations processing many requests	❌ No
Programmatic response parsing	❌ No

Send a Message

Standard non-streaming endpoint reference

Tokens

How token reporting differs between streaming and standard responses

Tool Use

Streaming and tool use can be combined in production applications

Error Handling

Handle errors that occur mid-stream

Authorizations

x-api-key

string

header

required

Headers

anthropic-version

string

required

Example:

"2023-06-01"

Body

application/json

model

enum<string>

required

The Claude model to use.

Available options:

claude-sonnet-4-6,

claude-opus-4-6,

claude-haiku-4-5

Example:

"claude-sonnet-4-6"

max_tokens

integer

required

Maximum number of output tokens to generate.

Required range: x >= 1

Example:

1024

messages

object[]

required

Show child attributes

stream

boolean

Set to true to enable streaming.

Example:

true

Response

Streaming response — returns Server-Sent Events

A stream of Server-Sent Events. Each event has a type and data field.

Multi-turn Conversation Tool Use

Endpoints

Overview

Why Use Streaming

The Event Lifecycle

Understanding Each Event

Extracting the Text

Chunk Size Is Variable

Token Reporting in Streaming

Markdown in Streaming Responses

When Not to Use Streaming

Further Reading

Send a Message

Tokens

Tool Use

Error Handling

Authorizations

Headers

Body

Response

​Overview

​Why Use Streaming

​The Event Lifecycle

​Understanding Each Event

​Extracting the Text

​Chunk Size Is Variable

​Token Reporting in Streaming

​Markdown in Streaming Responses

​When Not to Use Streaming

​Further Reading

Send a Message

Tokens

Tool Use

Error Handling

Authorizations

Headers

Body

Response

Overview

Why Use Streaming

The Event Lifecycle

Understanding Each Event

Extracting the Text

Chunk Size Is Variable

Token Reporting in Streaming

Markdown in Streaming Responses

When Not to Use Streaming

Further Reading