ChatResponseChunk

---

The ChatResponseChunk object containing a chunk of streaming chat response data.

Each chunk has a type indicating its kind. The other attributes that are present depend on that type.

Attributes

type (String)

The kind of chunk. One of:

• "text" - A portion of the response text.
• "reasoning" - A portion of the model's reasoning/thinking output.
• "reasoning_start" - A replayable reasoning block has opened (Claude only). Followed by "reasoning" deltas and a closing "reasoning_detail".
• "reasoning_detail" - A verbatim, replayable reasoning artifact — push it into message.reasoning_details to replay the turn.
• "image" - An image generated by an image-capable model.
• "tool_use" - A tool/function the model wants to call.
• "tool_use_start" - A tool call has started (only when streamToolInput is set). Followed by "tool_input_delta" chunks and a closing "tool_use".
• "tool_input_delta" - An incremental slice of a tool call's JSON arguments (only when streamToolInput is set).
• "server_tool" - A server-executed tool call or result (e.g. a web search), in the upstream's native shape.
• "safeguard_results" - Dangerous-tool-use classifier verdicts, keyed by the tool_use id they judged (Claude only, only when the upstream sent them).
• "compaction" - An inline-compaction summary of earlier context (when compaction is enabled).
• "extra_content" - Provider-specific metadata.
• "usage" - Token usage totals, emitted as the final chunk.
• "error" - An error raised while the response was streaming. Ends the stream.

text (String)

A portion of the chat response text. Present on text chunks.

reasoning (String)

A portion of the model's reasoning output. Present on reasoning chunks.

format (String)

The reasoning artifact format (currently only "anthropic"). Present on reasoning_start chunks — marks the reasoning that follows as replayable.

detail (Object)

A verbatim, replayable reasoning artifact — a signed thinking block, a redacted_thinking block, or an OpenAI Responses reasoning item. Present on reasoning_detail chunks.

image (Object)

A generated image, in the form { type: "image_url", image_url: { url } } where url is a data URI. Present on image chunks.

id (String)

The unique identifier for the tool call (tool_use, tool_use_start, tool_input_delta chunks) or the compaction item (compaction chunks).

encrypted_content (String)

The opaque/encrypted compaction summary. Present on compaction chunks. The shape is identical across providers — resend this item in messages on the next turn in place of the summarized history.

name (String)

The name of the function/tool to call. Present on tool_use and tool_use_start chunks.

input (Object)

The parsed arguments for the tool call. Present on tool_use chunks.

partialJson (String)

An incremental slice of a tool call's JSON arguments, in the order generated. Present on tool_input_delta chunks — concatenate and parse once the matching tool_use chunk arrives.

block (Object)

A server-executed tool call or result block (server_tool_use, web_search_tool_result, …), in the upstream's native shape. Present on server_tool chunks.

results (Array)

Dangerous-tool-use classifier verdicts. Present on safeguard_results chunks.

extra_content

Provider-specific metadata attached to the stream.

usage (Object)

An object containing token usage totals, plus cost: what the request was charged to the user, in microcents ($0.01 = 1,000,000). Present on the final usage chunk.

finish_reason (String)

OpenAI-vocabulary finish reason, derived from stopReason. Present on the final usage chunk.

stopReason (String)

The native stop reason (Anthropic vocabulary: end_turn, max_tokens, tool_use, pause_turn, refusal, …). Present on the final usage chunk.

stopSequence (String | null)

The stop sequence that ended generation, when one did. Present on the final usage chunk.

stopDetails (Object | null)

Extra detail on why generation stopped (e.g. a refusal classification). Provider-specific. Present on the final usage chunk.

usageDetails (Object)

A provider-neutral usage breakdown, present on the final usage chunk. inputTokens excludes cache reads/writes; outputTokens includes reasoning tokens. Fields: inputTokens, outputTokens, cacheReadTokens, cacheWrite5mTokens, cacheWrite1hTokens, reasoningTokens, webSearchRequests, webFetchRequests, speed ("fast" or "standard"), serviceTier, and iterations (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call).

message (String)

A description of the error that interrupted the response. Present on error chunks.

code (String)

The upstream's own error type/code (e.g. overloaded_error), when known. Present on error chunks.

status (Number)

The HTTP status the error maps to. Present on error chunks.