Streaming

Subscribe to GET /v1/runs/{runId}/sse to observe behavior in real time.

Include optional query parameter includeToolCalls if you want to have detailed request/response to be included for step event types.

Event Format

id: <sequential_int>
event: <event_name>
data: <json>

Special heartbeat:

event: keepalive
data: null

A keepalive is emitted every 20 s while at least one client is connected.

Data Events

Event	Description
start	The run begins execution.
step	A step inside the run finishes. Can be used for giving updates to end user about how run is progressing.
authentication	The run needs user authentication (status transitions to AUTH_REQUIRED) or reports its outcome.
run_approval	The run requires manual approval before proceeding (Emitted if Create Run request has approval strategy set).
run_action	Records the approval decision made by the user (approved or denied).
status	Any other status change (e.g. QUEUED, PAUSED).
end	The run finishes (SUCCESS, FAILED, or CANCELED).

Every data event contains:

{
    runId: string
    runStatus: "QUEUED" | "RUNNING" | "SUCCESS" | "FAILED" | "CANCELED" | "AUTH_REQUIRED" | "PAUSED"
    timestamp: (ISO-8601 string)
}

Payload reference

start

{
  "runId": string,
  "runStatus": "RUNNING",
  "timestamp": ISO-8601 string
}

step

{
  "runId": string,
  "runStatus": "RUNNING" | "PAUSED",
  "timestamp": ISO-8601 string,
  "step": {
    "reason": string,
    "approval": "APPROVED" | "DENIED" | "PENDING" | "NOT_REQUIRED",
    "approvalActions"?: [{
      "action": "approve" | "deny",
      "url": string
    }],
    "toolCalls"?: [{
      "toolCallId": string,
      "toolName": string,
      "toolParameters": object,
      "toolResult"?: {
          "approvalResult": { "status": string, "text": string },
          "executionResult": object
      }
    }],
    "text"?: string
  }
}

authentication

{
  "runId": string,
  "runStatus": "AUTH_REQUIRED" | "RUNNING" | "FAILED",
  "timestamp": ISO-8601 string,
  "auth":
    | { "status": "required", "url": string, "integrationName": string }
    | { "status": "success" }
    | { "status": "denied" }
}

run_approval

{
  "runId": string,
  "runStatus": "PAUSED",
  "timestamp": ISO-8601 string,
  "approvalActions": [{
      "action": "approve" | "deny",
      "url": string
    }]

}

run_action

{
  "runId": string,
  "runStatus": "RUNNING" | "CANCELED",
  "timestamp": ISO-8601 string,
  "action": "approved" | "denied"
}

status (queued / paused)

{
  "runId": string,
  "runStatus": "QUEUED" | "PAUSED",
  "timestamp": ISO-8601 string,
  "reason"?: string
}

end

{
  "runId": string,
  "runStatus": "SUCCESS" | "FAILED" | "CANCELED",
  "timestamp": ISO-8601 string,
  "result": {
    "text": string,
    "structuredOutput"?: (user provided output schema)
  }
}