Stream Task Logs - BLACKBOX AI

curl -N 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs/stream' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

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

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

data: {"type":"tool-input-available","toolCallId":"tc_001","toolName":"bash","input":{"command":"git clone https://github.com/org/repo.git /vercel/sandbox"}}

data: {"type":"tool-output-available","toolCallId":"tc_001","toolName":"bash","output":{"stdout":"Cloning into '/vercel/sandbox'...\ndone.","exitCode":0}}

data: {"type":"text-delta","id":"msg_abc123","delta":"Repository cloned successfully. Now adding the README..."}

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

GET

api

tasks

{runId}

logs

stream

curl -N 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs/stream' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

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

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

data: {"type":"tool-input-available","toolCallId":"tc_001","toolName":"bash","input":{"command":"git clone https://github.com/org/repo.git /vercel/sandbox"}}

data: {"type":"tool-output-available","toolCallId":"tc_001","toolName":"bash","output":{"stdout":"Cloning into '/vercel/sandbox'...\ndone.","exitCode":0}}

data: {"type":"text-delta","id":"msg_abc123","delta":"Repository cloned successfully. Now adding the README..."}

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

This endpoint provides a real-time SSE stream of task execution events. For live tasks it subscribes to the in-memory event buffer and pushes events as they arrive. For completed tasks it replays all persisted events in a single burst and closes the stream.

The event type values are the same regardless of agent runtime — Claude and Codex tasks emit an identical contract (session-init, text-delta, tool-call-start, tool-input-available, tool-output-available, result, …). See the full event table.

Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
Once provisioning completes, you will be redirected to your Dashboard
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

Path Parameters

runId

string

required

The unique run identifier returned when the task was created.Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query Parameters

includeDeltas

boolean

default:"true"

Whether to include text-delta events (individual text chunks). Set to false for a cleaner stream with only structural events.Default: true

Response Format

The endpoint returns Content-Type: text/event-stream. Each event is a JSON object on a data: line:

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

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

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

Event Types

text-start

event

Beginning of a new text block from the agent.Fields: id — message identifier

text-delta

event

Incremental text chunk from the agent.Fields: id, delta — text chunk string

tool-call-start

event

Agent started a tool call.Fields: toolCallId, toolName

tool-input-available

event

Tool call input is ready.Fields: toolCallId, toolName, input — tool input object

tool-output-available

event

Tool call result is available.Fields: toolCallId, toolName, output — tool output object

task-files

event

Files produced by the task.Fields: files — array of file objects

finish

event

Task completed (stream closes after this).Fields: runId, status

error

event

Task failed (stream closes after this).Fields: errorText

curl -N 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs/stream' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

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

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

data: {"type":"tool-input-available","toolCallId":"tc_001","toolName":"bash","input":{"command":"git clone https://github.com/org/repo.git /vercel/sandbox"}}

data: {"type":"tool-output-available","toolCallId":"tc_001","toolName":"bash","output":{"stdout":"Cloning into '/vercel/sandbox'...\ndone.","exitCode":0}}

data: {"type":"text-delta","id":"msg_abc123","delta":"Repository cloned successfully. Now adding the README..."}

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

Error Codes

Status Code	Error	Description
200	Success	SSE stream established
401	Unauthorized	Invalid or missing API key
403	Forbidden	Task belongs to a different user
404	Not Found	Task not found
409	Conflict	No logs available to stream
500	Internal Server Error	Failed to start stream

Get Task Logs Agent Run Status

​Authentication

​Headers

​Path Parameters

​Query Parameters

​Response Format

​Event Types

​Error Codes

Authentication

Headers

Path Parameters

Query Parameters

Response Format

Event Types

Error Codes