Skip to main content
GET
/
api
/
v1
/
agent
/
stream
curl -N 'https://agent.blackbox.ai/api/v1/agent/stream?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

data: {"type":"resume","runId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}

data: {"type":"start","runId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","startedAt":"2026-05-19T10:00:02.000Z"}

data: {"type":"text-start","id":"msg_abc123"}

data: {"type":"text-delta","id":"msg_abc123","delta":"I'll start by examining the repository structure..."}

data: {"type":"tool-call-start","toolCallId":"tc_001","toolName":"bash"}

data: {"type":"tool-input-available","toolCallId":"tc_001","toolName":"bash","input":{"command":"ls /vercel/sandbox"}}

data: {"type":"tool-output-available","toolCallId":"tc_001","toolName":"bash","output":{"stdout":"src\npackage.json\nREADME.md","exitCode":0}}

data: {"type":"text-delta","id":"msg_abc123","delta":"The repository has a standard Node.js structure. Creating the French README now..."}

data: {"type":"finish","runId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"completed"}
This endpoint provides the raw SSE stream for a specific agent run. It replays all buffered events from the start of the run and then streams new events as they arrive. The stream closes automatically when the run finishes or the client disconnects.
Events are emitted with the same type contract for both agent runtimes (Claude and Codex). See the full event table.

​
Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:
  1. Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your Dashboard
  3. From the Dashboard, create an API key to use with all Agent API requests
Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

​
Headers

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

​
Query Parameters

​
runId
string
required
The unique run identifier returned when the task was created.Example: runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Response Format

Returns Content-Type: text/event-stream. Each event is a JSON object on a data: line: 
data: {"type":"resume","runId":"..."}

data: {"type":"start","runId":"...","startedAt":"..."}

data: {"type":"text-delta","id":"...","delta":"Hello"}

data: {"type":"finish","runId":"...","status":"completed"}

​
Event Types

​
resume
event
Sent immediately on connection. Confirms the stream is live.Fields: type, runId
​
start
event
Sent when the agent run begins executing.Fields: type, runId, startedAt
​
text-start
event
Beginning of a new text block.Fields: type, id
​
text-delta
event
Incremental text chunk from the agent.Fields: type, id, delta
​
tool-call-start
event
Agent started a tool call.Fields: type, toolCallId, toolName
​
tool-input-available
event
Tool call input is ready.Fields: type, toolCallId, toolName, input
​
tool-output-available
event
Tool call result is available.Fields: type, toolCallId, toolName, output
​
task-files
event
Files produced by the task.Fields: type, files
​
finish
event
Run completed. Stream closes after this event.Fields: type, runId, status
​
error
event
Run failed. Stream closes after this event.Fields: type, errorText
curl -N 'https://agent.blackbox.ai/api/v1/agent/stream?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

data: {"type":"resume","runId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}

data: {"type":"start","runId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","startedAt":"2026-05-19T10:00:02.000Z"}

data: {"type":"text-start","id":"msg_abc123"}

data: {"type":"text-delta","id":"msg_abc123","delta":"I'll start by examining the repository structure..."}

data: {"type":"tool-call-start","toolCallId":"tc_001","toolName":"bash"}

data: {"type":"tool-input-available","toolCallId":"tc_001","toolName":"bash","input":{"command":"ls /vercel/sandbox"}}

data: {"type":"tool-output-available","toolCallId":"tc_001","toolName":"bash","output":{"stdout":"src\npackage.json\nREADME.md","exitCode":0}}

data: {"type":"text-delta","id":"msg_abc123","delta":"The repository has a standard Node.js structure. Creating the French README now..."}

data: {"type":"finish","runId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"completed"}

​
Error Codes

Status CodeErrorDescription
200SuccessSSE stream established
400Bad RequestMissing runId query parameter
401UnauthorizedInvalid or missing API key
409ConflictRun is not in a streamable state (not found or no buffer)