Streaming
Subscribe to thread updates using bidirectional gRPC streaming or Server-Sent Events (SSE).
Overview
The Thread API provides two methods for streaming real-time thread events: gRPC bidirectional streaming and REST API Server-Sent Events (SSE). Both methods deliver incremental message chunks, artifacts, and completion events as they occur during thread execution.
Choose the method that best fits your infrastructure:
- gRPC streaming
- SSE streaming
Server-Sent Events (SSE)
The SSE endpoint (GET /v2/threads/stream/{thread_id}) establishes a persistent HTTP connection that streams events as they occur. Open the stream connection before calling POST /v2/threads/{thread_id}/messages to capture all events.
How SSE streaming works
The server pushes events in this typical flow:
message_work_in_progresslogs may appear before or between chunks, indicating background processing.message_chunkevents arrive incrementally as the AI generates its response. Each chunk contains the partial text undermessage_chunk.messageand afinal_chunkboolean flag.- When
final_chunk: truearrives, the complete message is ready. messageevents signal that a complete message has been assembled.task_statusorexecution_statusevents report progress. Whenstatus: "Complete"appears, the thread is idle.
Basic usage
If the SSE channel closes before completion, call GET /v2/threads/{thread_id}/progress to check status. Issue DELETE /v2/threads/{thread_id}/task when a user manually stops work.
Complete SSE example
The following example demonstrates the full workflow: creating a thread, establishing an SSE stream, sending a message, and processing real-time events until completion.
The script uses Python’s threading module to establish the SSE stream before sending the message, ensuring all events are captured:
Set the ALFA_ACCESS_TOKEN environment variable with your OAuth2 access token obtained via token exchange. See the authorization guide for details. The threading synchronization ensures the SSE listener is ready before the message triggers any events, preventing lost chunks.
SSE event types
The stream emits several event types. Here are the most common:
Work in progress logs (background processing updates):
Message chunks (incremental response text):
Final chunk (last piece of the message):
Complete message (with metadata and tools):
Artifacts are JSON strings embedded in the message text (wrapped in triple backticks). Use GET /v2/threads/{thread_id}/artifacts/{artifact_id} to fetch the actual artifact data.
Task status (progress updates):
The message text is located at event.message_chunk.message. When final_chunk: true appears, the complete message is ready. The client must parse any artifact markers from the message text to extract artifact_id values. The script continues listening until it receives a task_status event with status: "Complete", signaling that all processing has finished.
gRPC bidirectional streaming
Protocol buffer definition
Download and compile the following protocol buffer file to generate client stubs:
Building the client
Generate client code from the proto file using the gRPC tools for your language.
Python:
This generates:
thread_service_pb2.py: Protocol buffer message classesthread_service_pb2_grpc.py: gRPC service stub classesthread_service_pb2.pyi: Type stubs for type checking
Go:
This generates Go code locally. Update the go_package option in the proto file to match your module path, or import the generated code using the path specified in go_package.
gRPC connection setup
Establish a secure gRPC channel with keepalive settings to maintain the connection:
The keepalive settings ensure the connection remains active even during periods of inactivity, preventing timeouts.
Complete gRPC example
The following example demonstrates subscribing to thread events via gRPC streaming:
How gRPC streaming works
- Create a secure channel with SSL credentials and keepalive options to maintain the connection.
- Create a request generator that yields the initial subscription request with
thread_id,user_token, andsubscribe=True. The generator continues running to keep the stream alive. - Call the streaming RPC using the generated stub, passing the request generator and authentication metadata.
- Iterate over responses as they arrive. Each
StreamThreadEventsResponsecontains:thread_id: The thread the event belongs touser_ids: List of user IDs that requested accessthread_data: AThreadDatamessage containing the event payload
The thread_data field is a ThreadData message with a oneof payload that can be one of:
message_event: A complete message with citationsmessage_chunk_event: An incremental message chunk (checkfinal_chunkfor completion)work_in_progress_event: Background processing statusthread_name_event: Thread name updatesworker_error_event: Error notificationsmessage_cancelled_event: Cancellation confirmations
The request generator must continue yielding or sleeping to keep the bidirectional stream alive. If the generator exits, the stream will close.
Authentication
gRPC streaming uses Bearer token authentication via metadata. Include your service account token in the metadata:
Obtain your service account token from your Boosted account. See the authorization guide for details. Ensure your token has permission to access the specified thread.
