OpenAI Responses API — SSE Streaming Internals#

Source: OpenAI Python SDK openai-python (Stainless-generated)
Scope: SSE (Server-Sent Events) only. WebSocket mode excluded.
Last updated: 2026-06-20

1. High-Level Architecture#

1
flowchart TB
2
    subgraph User["User Code"]
3
        A["client.responses.create(stream=True)"]
4
    end
5
    subgraph HTTP["HTTP POST /v1/responses"]
6
        B["POST /v1/responses<br/>headers: text/event-stream<br/>body: { stream: true }"]
7
    end
8
    subgraph SSE["SSE Decoding"]
9
        C["SSEDecoder.decode(line)"]
10
        D["ServerSentEvent"]
11
        E["construct_type(discriminator=type)"]
12
    end
13
    subgraph SDK["SDK Layer"]
14
        F["ResponseStreamState<br/>(accumulate + handle)"]
15
        G["ResponseStreamEvent[]"]
16
    end
17
    A --> B
18
    B -->|chunked transfer| C
19
    C -->|line by line| D
20
    D -->|JSON dict| E
21
    E -->|typed event| F
22
    F -->|yields| G

or via the convenience API:

1
with client.responses.stream(input="...", model="gpt-4o") as stream:
2
    for event in stream:
3
        ...

which uses ResponseStreamManager → ResponseStream internally.

2. SSE Wire Format#

Unlike the Assistants API (which uses named SSE event: fields like thread.message.delta), the Responses API embeds the event type directly in the JSON payload as a type field.

Each SSE chunk looks like:

1
data: {"type":"response.created","response":{...},"sequence_number":0}
2

3
data: {"type":"response.in_progress","response":{...},"sequence_number":1}
4

5
data: {"type":"response.output_item.added","output_index":0,"item":{...},"sequence_number":2}
6

7
data: {"type":"response.content_part.added","output_index":0,"item_id":"...","content_index":0,"part":{...},"sequence_number":3}
8

9
data: {"type":"response.output_text.delta","output_index":0,"item_id":"...","content_index":0,"delta":"Hello","sequence_number":4}
10
...

event: line is not set for Responses API SSE events.
The type field inside the JSON body is the discriminator.
Every event has a sequence_number: int for ordering.
The stream ends when the connection closes (no [DONE] sentinel for Responses; the [DONE] check in Stream._iter_events is only for legacy Chat Completions).

3. Full Event Catalog (53 types)#

3.1 Response Lifecycle Events#

#	type literal	Class	Fields
1	response.created	`ResponseCreatedEvent`	response: Response, sequence_number: int
2	response.queued	ResponseQueuedEvent	response: Response, sequence_number: int
3	response.in_progress	ResponseInProgressEvent	response: Response, sequence_number: int
4	response.completed	`ResponseCompletedEvent`	response: Response, sequence_number: int
5	response.failed	ResponseFailedEvent	response: Response, sequence_number: int
6	response.incomplete	ResponseIncompleteEvent	response: Response, sequence_number: int
7	error	ResponseErrorEvent	code: Optional[str], message: str, param: Optional[str], sequence_number: int

3.2 Output Items — Structural#

#	type literal	Class	Fields
8	response.output_item.added	ResponseOutputItemAddedEvent	item: `ResponseOutputItem`, output_index: int, sequence_number: int
9	response.output_item.done	ResponseOutputItemDoneEvent	item: `ResponseOutputItem`, output_index: int, sequence_number: int
10	response.content_part.added	ResponseContentPartAddedEvent	part: Part, content_index: int, item_id: str, output_index: int, sequence_number: int
11	response.content_part.done	ResponseContentPartDoneEvent	part: Part, content_index: int, item_id: str, output_index: int, sequence_number: int

Part is a discriminated union of:

ResponseOutputText (type=output_text)
ResponseOutputRefusal (type=refusal)
PartReasoningText (type=reasoning_text)

3.3 Text Content#

#	type literal	Class	Fields
12	response.output_text.delta	`ResponseTextDeltaEvent`	delta: str, content_index: int, item_id: str, output_index: int, logprobs: List[Logprob], sequence_number: int
13	response.output_text.done	`ResponseTextDoneEvent`	text: str, content_index: int, item_id: str, output_index: int, logprobs: List[Logprob], sequence_number: int
14	response.output_text.annotation.added	ResponseOutputTextAnnotationAddedEvent	annotation: object, annotation_index: int, content_index: int, item_id: str, output_index: int, sequence_number: int

logprob structure:

1
Logprob:
2
  token: str
3
  logprob: float
4
  top_logprobs: Optional[List[LogprobTopLogprob]]  # up to 20 alternatives
5

6
LogprobTopLogprob:
7
  token: Optional[str]
8
  logprob: Optional[float]

3.4 Refusal#

#	type literal	Class	Fields
15	response.refusal.delta	ResponseRefusalDeltaEvent	delta: str, content_index: int, item_id: str, output_index: int, sequence_number: int
16	response.refusal.done	ResponseRefusalDoneEvent	refusal: str, content_index: int, item_id: str, output_index: int, sequence_number: int

3.5 Function Calling#

#	type literal	Class	Fields
17	response.function_call_arguments.delta	`ResponseFunctionCallArgumentsDeltaEvent`	delta: str, item_id: str, output_index: int, sequence_number: int
18	response.function_call_arguments.done	ResponseFunctionCallArgumentsDoneEvent	arguments: str, name: str, item_id: str, output_index: int, sequence_number: int

3.6 MCP (Model Context Protocol)#

#	type literal	Class	Fields
19	response.mcp_call.in_progress	ResponseMcpCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
20	response.mcp_call_arguments.delta	ResponseMcpCallArgumentsDeltaEvent	delta: str (JSON partial), item_id: str, output_index: int, sequence_number: int
21	response.mcp_call_arguments.done	ResponseMcpCallArgumentsDoneEvent	arguments: str (JSON full), item_id: str, output_index: int, sequence_number: int
22	response.mcp_call.completed	ResponseMcpCallCompletedEvent	item_id: str, output_index: int, sequence_number: int
23	response.mcp_call.failed	ResponseMcpCallFailedEvent	item_id: str, output_index: int, sequence_number: int
24	response.mcp_list_tools.in_progress	ResponseMcpListToolsInProgressEvent	item_id: str, output_index: int, sequence_number: int
25	response.mcp_list_tools.completed	ResponseMcpListToolsCompletedEvent	item_id: str, output_index: int, sequence_number: int
26	response.mcp_list_tools.failed	ResponseMcpListToolsFailedEvent	item_id: str, output_index: int, sequence_number: int

3.7 Audio#

#	type literal	Class	Fields
27	response.audio.delta	ResponseAudioDeltaEvent	delta: str (Base64 audio bytes), sequence_number: int
28	response.audio.done	ResponseAudioDoneEvent	sequence_number: int
29	response.audio.transcript.delta	ResponseAudioTranscriptDeltaEvent	delta: str, sequence_number: int
30	response.audio.transcript.done	ResponseAudioTranscriptDoneEvent	sequence_number: int

3.8 Web Search Tool#

#	type literal	Class	Fields
31	response.web_search_call.in_progress	ResponseWebSearchCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
32	response.web_search_call.searching	ResponseWebSearchCallSearchingEvent	item_id: str, output_index: int, sequence_number: int
33	response.web_search_call.completed	ResponseWebSearchCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.9 File Search Tool#

#	type literal	Class	Fields
34	response.file_search_call.in_progress	ResponseFileSearchCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
35	response.file_search_call.searching	ResponseFileSearchCallSearchingEvent	item_id: str, output_index: int, sequence_number: int
36	response.file_search_call.completed	ResponseFileSearchCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.10 Code Interpreter Tool#

#	type literal	Class	Fields
37	response.code_interpreter_call.in_progress	ResponseCodeInterpreterCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
38	response.code_interpreter_call.interpreting	ResponseCodeInterpreterCallInterpretingEvent	item_id: str, output_index: int, sequence_number: int
39	response.code_interpreter_call_code.delta	ResponseCodeInterpreterCallCodeDeltaEvent	delta: str, item_id: str, output_index: int, sequence_number: int
40	response.code_interpreter_call_code.done	ResponseCodeInterpreterCallCodeDoneEvent	code: str, item_id: str, output_index: int, sequence_number: int
41	response.code_interpreter_call.completed	ResponseCodeInterpreterCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.11 Reasoning#

#	type literal	Class	Fields
42	response.reasoning_text.delta	ResponseReasoningTextDeltaEvent	delta: str, content_index: int, item_id: str, output_index: int, sequence_number: int
43	response.reasoning_text.done	ResponseReasoningTextDoneEvent	text: str, content_index: int, item_id: str, output_index: int, sequence_number: int
44	response.reasoning_summary_part.added	ResponseReasoningSummaryPartAddedEvent	part: Part (summary_text), summary_index: int, item_id: str, output_index: int, sequence_number: int
45	response.reasoning_summary_part.done	ResponseReasoningSummaryPartDoneEvent	part: Part (summary_text), summary_index: int, item_id: str, output_index: int, sequence_number: int
46	response.reasoning_summary_text.delta	ResponseReasoningSummaryTextDeltaEvent	delta: str, summary_index: int, item_id: str, output_index: int, sequence_number: int
47	response.reasoning_summary_text.done	ResponseReasoningSummaryTextDoneEvent	text: str, summary_index: int, item_id: str, output_index: int, sequence_number: int

3.12 Image Generation#

#	type literal	Class	Fields
48	response.image_generation_call.in_progress	ResponseImageGenCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
49	response.image_generation_call.generating	ResponseImageGenCallGeneratingEvent	item_id: str, output_index: int, sequence_number: int
50	response.image_generation_call.partial_image	ResponseImageGenCallPartialImageEvent	partial_image_b64: str, partial_image_index: int (0-based), item_id: str, output_index: int, sequence_number: int
51	response.image_generation_call.completed	ResponseImageGenCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.13 Custom Tool Call#

#	type literal	Class	Fields
52	response.custom_tool_call_input.delta	ResponseCustomToolCallInputDeltaEvent	delta: str, item_id: str, output_index: int, sequence_number: int
53	response.custom_tool_call_input.done	ResponseCustomToolCallInputDoneEvent	input: str, item_id: str, output_index: int, sequence_number: int

4. SSE Parsing Pipeline (Wire to Typed Event)#

1
flowchart TB
2
    subgraph HTTP["HTTP Response Stream"]
3
        A["httpx.Response.iter_bytes()"]
4
    end
5
    subgraph SSE["SSE Decoder (WHATWG SSE)"]
6
        B["SSEDecoder.decode(line)"]
7
        C["ServerSentEvent<br/>.event - None for Responses<br/>.data - raw JSON string"]
8
    end
9
    subgraph DISPATCH["Stream Dispatcher"]
10
        D{"sse.data starts with [DONE]?"}
11
        E{"sse.event starts with thread.?"}
12
        F["construct_type(discriminator=type)"]
13
    end
14
    subgraph OUT["Typed Event"]
15
        G["ResponseCreatedEvent |<br/>ResponseTextDeltaEvent |<br/>... (52 more types)"]
16
    end
17
    A --> B
18
    B --> C
19
    C --> D
20
    D -->|yes| H["break (legacy)"]
21
    D -->|no| E
22
    E -->|yes| I["thread. events (Assistants)"]
23
    E -->|no| F
24
    F --> G

Key decoder details#

SSEDecoder accumulates lines until a blank line (\n\n, \r\r, or \r\n\r\n).
Each SSE field (event:, data:, id:, retry:) is processed per spec.
For Responses, event: is absent → ServerSentEvent.event is None.
The raw JSON data: is deserialized and passed to construct_type().
ResponseStreamEvent is Annotated[Union[…], PropertyInfo(discriminator=“type”)], so construct_type examines the “type” key to dispatch to the correct subclass.

5. SDK Convenience API: `ResponseStream` / `ResponseStreamState`#

5.1 `ResponseStreamManager` (entry point)#

Usage:

1
with client.responses.stream(
2
    input="Hello", model="gpt-4o"
3
) as stream:  # returns ResponseStream[TextFormatT]
4
    for event in stream:
5
        ...

The manager:

Calls client.responses.create(stream=True, …) to get the raw Stream[ResponseStreamEvent].
Wraps it in ResponseStream(raw_stream=…, text_format=…, input_tools=…).
Exposes the stream as an iterator of ResponseStreamEvent[TextFormatT].

5.2 `ResponseStream` → `ResponseStreamState`#

ResponseStream.__stream__() delegates to ResponseStreamState.handle_event(sse_event) for each raw event.

handle_event() produces 1 or 2 events per raw SSE event:

Raw SSE type	Emitted events
response.output_text.delta	`ResponseTextDeltaEvent` (with snapshot field added — accumulated text so far)
response.output_text.done	`ResponseTextDoneEvent` (with parsed field if text_format is set)
response.function_call_arguments.delta	`ResponseFunctionCallArgumentsDeltaEvent` (with snapshot — accumulated args so far)
response.completed	`ResponseCompletedEvent` (with response being the full parsed `ParsedResponse`)
All others	Passed through as-is

5.3 accumulate_event() — State Machine#

ResponseStreamState maintains a __current_snapshot (partial ParsedResponse):

response.created → Creates initial snapshot from event.response.
response.output_item.added → Appends item to snapshot.output[] (handles function_call, message, and generic types).
response.content_part.added → Appends content part to the indexed output message.
response.output_text.delta → Concatenates delta to the matching output_text content’s text.
response.function_call_arguments.delta → Concatenates delta to the matching function call’s arguments.
response.completed → Stores the fully parsed response via parse_response() (also handles structured output parsing).

5.4 Convenience methods#

stream.get_final_response() → Consumes entire stream, returns the accumulated ParsedResponse.
stream.until_done() → Blocks until stream fully consumed.
stream.close() → Closes underlying httpx response.

5.5 `ResponseStreamEvent`[TextFormatT] (SDK wrapper types)#

These subclass or wrap the raw generated types with extra fields:

Raw type	SDK wrapper	Extra fields
`ResponseTextDeltaEvent`	lib.streaming.responses.`ResponseTextDeltaEvent`	snapshot: str (accumulated text)
`ResponseTextDoneEvent`	lib.streaming.responses.`ResponseTextDoneEvent`	parsed: Optional[TextFormatT]
`ResponseFunctionCallArgumentsDeltaEvent`	lib.streaming.responses.`ResponseFunctionCallArgumentsDeltaEvent`	snapshot: str (accumulated args)
`ResponseCompletedEvent`	lib.streaming.responses.`ResponseCompletedEvent`	response: `ParsedResponse`[TextFormatT]

The composite ResponseStreamEvent type alias used by the stream is:

1
ResponseStreamEvent = Annotated[Union[
2
    ResponseTextDeltaEvent,       # SDK wrapper
3
    ResponseTextDoneEvent,        # SDK wrapper
4
    ResponseFunctionCallArgumentsDeltaEvent,  # SDK wrapper
5
    ResponseCompletedEvent,       # SDK wrapper
6
    ResponseAudioDeltaEvent,      # raw
7
    ... (all other raw events)    # raw
8
], PropertyInfo(discriminator="type")]

6. Background Mode Streaming#

When background=True is passed to responses.stream():

The API request includes “background”: true.
The server immediately returns a response.created event with the response id.
The stream stays open but yields events asynchronously as the background processing progresses.
The stream can be interrupted and resumed: note the response_id from response.created, then later call responses.stream(response_id=id, starting_after=N) to resume from sequence number N.

Usage pattern:

1
with client.responses.stream(input="...", model="gpt-4o", background=True) as stream:
2
    for event in stream:
3
        if event.type == "response.created":
4
            id = event.response.id
5
        if event.sequence_number == 10:
6
            break
7

8
# Later...
9
with client.responses.stream(response_id=id, starting_after=10) as stream:
10
    for event in stream:
11
        ...
12
    response = stream.get_final_response()

7. Data Flow Summary#

1
flowchart TB
2
    subgraph CLIENT["Client"]
3
        A["HTTP POST /v1/responses<br/>{ stream: true }"]
4
    end
5
    subgraph PROXY["HTTP Transport"]
6
        B["Content-Type: text/event-stream<br/>chunked transfer"]
7
    end
8
    subgraph PARSE["SSE Parser"]
9
        C["SSEDecoder<br/>- buffers \n\n chunks<br/>- parses event:/data:"]
10
    end
11
    subgraph DISP["Type Dispatch"]
12
        D["construct_type()<br/>via type discriminator"]
13
    end
14
    subgraph ACC["Accumulator"]
15
        E["ResponseStreamState<br/>- maintains snapshot<br/>- adds snapshot/parsed"]
16
    end
17
    subgraph USER["User"]
18
        F["for event in stream:"]
19
    end
20
    A --> B
21
    B --> C
22
    C --> D
23
    D --> E
24
    E --> F

8. Wire-Level Example (Synthetic)#

1
data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"queued","created_at":1718000000,"model":"gpt-4o","output":[],"tools":[],"tool_choice":"auto","parallel_tool_calls":true,"top_p":1,"temperature":1},"sequence_number":0}
2

3
data: {"type":"response.queued","response":{"id":"resp_abc123",...},"sequence_number":1}
4

5
data: {"type":"response.in_progress","response":{"id":"resp_abc123","status":"in_progress",...},"sequence_number":2}
6

7
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"item_1","type":"message","role":"assistant","content":[],"status":"in_progress"},"sequence_number":3}
8

9
data: {"type":"response.content_part.added","output_index":0,"item_id":"item_1","content_index":0,"part":{"type":"output_text","text":"","annotations":[]},"sequence_number":4}
10

11
data: {"type":"response.output_text.delta","output_index":0,"item_id":"item_1","content_index":0,"delta":"Hello","sequence_number":5,"logprobs":[{"token":"Hello","logprob":-0.01}]}
12

13
data: {"type":"response.output_text.delta","output_index":0,"item_id":"item_1","content_index":0,"delta":" world","sequence_number":6,"logprobs":[...]}
14

15
data: {"type":"response.output_text.done","output_index":0,"item_id":"item_1","content_index":0,"text":"Hello world","sequence_number":7,"logprobs":[...]}
16

17
data: {"type":"response.content_part.done","output_index":0,"item_id":"item_1","content_index":0,"part":{"type":"output_text","text":"Hello world","annotations":[]},"sequence_number":8}
18

19
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"item_1","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hello world","annotations":[]}],"status":"completed"},"sequence_number":9}
20

21
data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","output":[{"id":"item_1",...}],...},"sequence_number":10}

9. Implementation Reference (Key Files in SDK)#

File	Purpose
src/openai/_streaming.py	Stream[T], AsyncStream[T], SSEDecoder, SSEBytesDecoder, `ServerSentEvent`
src/openai/_response.py	APIResponse, _parse() → constructs Stream[T]
src/openai/_base_client.py	request(), _process_response(), _process_response_data(), _make_sse_decoder(), make_request_options()
src/openai/types/responses/response_stream_event.py	`ResponseStreamEvent` discriminated union
src/openai/lib/streaming/responses/_responses.py	`ResponseStream`, `AsyncResponseStream`, `ResponseStreamManager`, `ResponseStreamState`
src/openai/lib/streaming/responses/_events.py	SDK-enhanced wrapper types + `ResponseStreamEvent` (lib version)
src/openai/resources/responses/responses.py	Responses.create(), Responses.stream(), WebSocket connection code

10. Event Taxonomy Diagram#

1
graph LR
2
    subgraph LIFECYCLE["Response Lifecycle"]
3
        RC["response.created"] --> RQ["response.queued"]
4
        RQ --> RI["response.in_progress"]
5
        RI --> RC2["response.completed"]
6
        RI --> RF["response.failed"]
7
        RI --> RINC["response.incomplete"]
8
    end
9
    subgraph CONTENT["Content Delta"]
10
        OT["output_text.delta"] --> OTD["output_text.done"]
11
        OTD --> OTA["output_text.annotation"]
12
        RD["refusal.delta"] --> RD2["refusal.done"]
13
        AD["audio.delta"] --> ADD["audio.done"]
14
        ATD["audio.transcript.delta"] --> ATDD["audio.transcript.done"]
15
        RT["reasoning_text.delta"] --> RTD["reasoning_text.done"]
16
        RS["reasoning_summary_part<br/>reasoning_summary_text"]
17
    end
18
    subgraph STRUCT["Output Structure"]
19
        OIA["output_item.added"] --> OID["output_item.done"]
20
        CPA["content_part.added"] --> CPD["content_part.done"]
21
    end
22
    subgraph IMAGE["Image Generation"]
23
        IGI["image_gen_call.in_progress"] --> IGG["image_gen_call.generating"]
24
        IGG --> IGP["image_gen_call.partial_image"]
25
        IGP --> IGC["image_gen_call.completed"]
26
    end
27
    subgraph TOOLS["Tool Calls"]
28
        FC["function_call_arguments.delta/done"]
29
        MCP["mcp_call.* (8 events)"]
30
        WS["web_search_call.* (3 events)"]
31
        FS["file_search_call.* (3 events)"]
32
        CI["code_interpreter_call.* (5 events)"]
33
        CT["custom_tool_call_input.delta/done"]
34
    end
35
    LIFECYCLE --> CONTENT
36
    LIFECYCLE --> STRUCT
37
    LIFECYCLE --> TOOLS
38
    LIFECYCLE --> IMAGE

Pro tip: The SDK docstrings only document response.created. Use the type definitions from src/openai/types/responses/response__event.py as the canonical source. Every event has the type literal (matching the type field in the JSON), sequence_number: int, and event-specific fields.