The Messages API and Its MechanicsStreaming and what it costs you
No narration yet
Module 1, Lesson 318 min

Streaming and what it costs you

Streaming is the most boring feature with the highest production impact. It changes nothing about what you pay and everything about whether your app feels broken.

The event sequence

A streamed response is server-sent events. The envelope is stable enough to memorise in one sitting.

The order, every time
message_start          -> the shell, with input usage
  content_block_start  -> index 0 begins
  content_block_delta  -> ...tokens...
  content_block_stop   -> index 0 done
  (repeat per block)
message_delta          -> final stop_reason and output usage
message_stop           -> done

ping events can show up anywhere and carry no meaning. An error event can arrive mid-stream, which is the part people forget: a stream that started successfully can still fail halfway, so a 200 on the initial response is not a guarantee of a complete answer.

Reassemble by index, never by concatenation

Content blocks are indexed, and a single response can carry several. A model that writes a sentence and then calls two tools produces three block sequences interleaved in one stream.

If your client does buffer += delta.text you will be fine right up until the day a tool call appears, and then you will silently glue a tool's JSON input onto the end of your prose. Key by index from content_block_start. Parse a tool's arguments only once its content_block_stop has arrived, because the JSON arrives in fragments and is not valid until the last one.

Why you stream even when nobody is watching

The obvious reason is perceived latency. The less obvious one is that long generations are better served incrementally, and a non-streaming request has to hold a single connection open for the entire generation with nothing coming back down it. Timeouts, proxies and load balancers all hate that.

So the rule of thumb is: if the response could be long, stream it, even for a background job that has no human reading the output. You throw the deltas away and keep the final message. The cost is identical.

What streaming does not change

It does not change the price. It does not change the model's behaviour, the sampling, the tool loop, or the stop reasons. It does not give you the ability to cancel mid-generation and pay less for what you already received.

It is a delivery mechanism sitting on top of exactly the same request body, with "stream": true added. If a question offers you streaming as an answer to a cost problem, the answer it wants is Batches or caching.

Practice

Try it yourself

Recall

The shape of a stream

Describe the envelope of a streamed response without listing every event name.

What is the overall structure of a streamed Messages API response, and where do the actual tokens arrive?

Quiz

Does streaming change your bill

You switch a high-volume endpoint from non-streaming to streaming. What happens to the cost per request?

Quiz

Where final usage lands in a stream

Your billing dashboard reads output token counts off the stream. Which event must it listen for?

Check

Confirm you reassemble by index

Look at your own streaming client, or sketch one, and check how it handles a response with two tool calls in it.

You should see

Deltas are accumulated into a map or array keyed by the block index from content_block_start, never appended to a single flat string. A response containing one text block and two tool_use blocks reconstructs into three distinct blocks, and the tool inputs are parsed only after their content_block_stop arrives.