Skip to main content
Polling for results is effective, but for a more responsive, real-time experience, you can stream events directly from a running tool. This guide shows you how to connect to a tool’s event stream using Server-Sent Events (SSE). This guide assumes you have already started a tool execution as shown in the Executing Your First Tool guide.
1

Start a Tool Execution

First, execute a tool as you normally would. The initial 202 Accepted response will contain a stream_url. This is the endpoint we’ll use to receive live events.
Response
{
  "execution_id": "exec_123456789",
  "status": "pending",
  "tool_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "details_url": "https://app.ubik-agent.com/api/v1/tool-executions/exec_123456789",
  "stream_url": "https://app.ubik-agent.com/api/v1/tool-executions/exec_123456789/stream"
}
Copy the stream_url for the next step.
2

Connect to the Event Stream

Now, you can connect to the stream_url using any SSE-compatible client. The connection will remain open, and the server will push events as they happen.
# Use the -N flag to disable buffering
curl -X GET "https://app.ubik-agent.com/api/v1/tool-executions/exec_123456789/stream" \
     -H "X-API-KEY: YOUR_API_KEY" \
     -N
In the JavaScript EventSource example, we pass the API key as a query parameter. Our server is configured to accept the API key from either the X-API-KEY header or a query parameter named api_key for SSE connections, as EventSource does not support custom headers.
3

Understanding the Events

As the tool executes, you will receive a series of JSON objects. Each object contains an event_type and a data payload. Here are the main event types:
  • tool_update: A general progress update. The data payload often contains phase and message fields to describe the current state.
  • tool_partial_update: A chunk of streaming content. The data payload contains a content field with the text.
  • final_result: The final event of a successful execution, containing the complete outputs in the data payload.
  • tool_input_required: Sent when an interactive tool needs user input.
  • error: Indicates that an error occurred during execution.
Example Event Stream
data: {"event_type": "tool_update", "data": {"phase": "retrieval", "message": "Fetching relevant documents..."}}

data: {"event_type": "tool_update", "data": {"phase": "generation", "message": "Generating response..."}}

data: {"event_type": "tool_partial_update", "data": {"content": "The financial results show..."}}

data: {"event_type": "tool_partial_update", "data": {"content": " a significant increase in revenue."}}

data: {"event_type": "final_result", "data": {"outputs": {"response": "The financial results show a significant increase in revenue."}}}
By using Server-Sent Events, you can build highly interactive and responsive applications that react to long-running processes in real-time.