- Chat UIs that show responses as they arrive, before generation completes.
- Long-form generation (reports, code) where waiting for the full output hurts UX.
- Agent workflows that surface reasoning steps or tool calls in real time.
- Reducing perceived latency on slow models or large outputs.
Quick Start
Enable real-time response streaming for better user experience.Configuration
All models support streaming: no additional configuration needed.
Response Format
Streaming chunks:response.completed. It carries the response object, including usage and telemetry. The response.output_text.done event marks the end of the text only, so read past it until response.completed arrives.
Usage in the final chunk
stream_options: { "include_usage": true } mirrors the OpenAI format and is accepted. When the stream reports token usage for the whole request, it does so in a final chunk after the content chunk, sent before the [DONE] marker.
usage from whichever chunk carries it. Most requests send it in a chunk with an empty choices array, but a request that uses server tools sends it in the chunk that also carries finish_reason, so testing every chunk for usage is the reliable approach:
Code examples
Stream Processing Patterns
The examples in this section use the Chat Completions endpoint. The same patterns apply to the Responses API: replace
chat.completions.create(...) with responses.create(...), update the endpoint to /v3/router/responses, and handle response.output_text.delta events instead of choices[0].delta.content.Basic processing
Accumulate deltas into a full string and detect completion viafinish_reason.
With error handling
Guard against network drops and unexpected errors by wrapping the stream loop in a try/except. The TypeScript example additionally resets a timeout on each chunk.Function Calling with Streaming
Stream tool calls as theyāre generated:UI Integration Examples
React hook for streaming
Encapsulate streaming state in a hook so components receiveresponse and isStreaming without managing the event loop themselves.
Performance Optimization
Chunk buffering
Batching small chunks before flushing to the UI reduces render cycles and smooths perceived output.Memory management
For long completions, cap accumulation to avoid unbounded memory growth.Best Practices
Stream management
- Set reasonable timeouts (30-60 seconds).
- Implement proper error boundaries.
- Handle network interruptions gracefully.
- Provide user cancellation options.
UI/UX considerations
- Show typing indicators during streaming.
- Allow users to stop generation.
- Buffer small chunks for smoother display.
- Handle rapid updates efficiently.
Error recovery example
Troubleshooting
Stream cuts off unexpectedly- Check network stability.
- Verify timeout settings.
- Monitor for rate limiting.
- Check model-specific limits.
- Optimize chunk processing.
- Reduce buffer flush frequency.
- Check network latency.
- Consider model selection.
max_tokens implies more
than 10 minutes of generation returns 400 with type: "invalid_request_error".
Set stream: true for long outputs or reduce max_tokens.
Memory issues
- Implement chunk size limits.
- Use streaming parsers.
- Clear processed chunks.
- Monitor memory usage.
Limitations
A streamed model request runs for up to 30 minutes; an explicitlimits.max_execution_time lowers that cap. SDK clients apply their own request timeout to the whole call, so raise timeoutMs or timeout_ms before starting a long stream. See Timeouts and retries.
A dropped stream cannot be resumed: neither endpoint exposes a resume cursor or event replay. Re-issue the request. On the Responses API, if the server finished the response before the drop and it is still stored, continue from it with
previous_response_id. For work that must survive a disconnect, use background mode and poll the response ID instead of streaming.
Advanced Features
The examples in this section use the Chat Completions endpoint. The same patterns apply to the Responses API: replace
chat.completions.create(...) with responses.create(...). For cURL, use /v3/router/responses.Stream with other Gateway features
AI Gateway features like caching, timeouts, and deployment names compose directly with streaming: add them to the same request object.Parallel streaming
Fire multiple streams concurrently usingPromise.all in TypeScript and asyncio.gather in Python to get independent responses without waiting for each to finish.

