Get Task Logs - BLACKBOX AI

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

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chatId": "chat_def789ghi012",
  "status": "completed",
  "source": "reconstructed",
  "eventCount": 5,
  "events": [
    {
      "type": "text-start",
      "id": "msg_abc123"
    },
    {
      "type": "tool-call-start",
      "toolCallId": "tc_001",
      "toolName": "bash"
    },
    {
      "type": "tool-input-available",
      "toolCallId": "tc_001",
      "toolName": "bash",
      "input": { "command": "ls -la /vercel/sandbox" }
    },
    {
      "type": "tool-output-available",
      "toolCallId": "tc_001",
      "toolName": "bash",
      "output": { "stdout": "total 8\ndrwxr-xr-x 2 root root 4096 ...", "exitCode": 0 }
    },
    {
      "type": "finish",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed"
    }
  ],
  "error": null
}

GET

api

tasks

{runId}

logs

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

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chatId": "chat_def789ghi012",
  "status": "completed",
  "source": "reconstructed",
  "eventCount": 5,
  "events": [
    {
      "type": "text-start",
      "id": "msg_abc123"
    },
    {
      "type": "tool-call-start",
      "toolCallId": "tc_001",
      "toolName": "bash"
    },
    {
      "type": "tool-input-available",
      "toolCallId": "tc_001",
      "toolName": "bash",
      "input": { "command": "ls -la /vercel/sandbox" }
    },
    {
      "type": "tool-output-available",
      "toolCallId": "tc_001",
      "toolName": "bash",
      "output": { "stdout": "total 8\ndrwxr-xr-x 2 root root 4096 ...", "exitCode": 0 }
    },
    {
      "type": "finish",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed"
    }
  ],
  "error": null
}

This endpoint returns the complete execution log for a task as an array of parsed events. It automatically selects the best available source — live in-memory buffer for running tasks, or reconstructed events from the database for completed tasks.

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 smaller, summarized payload.Default: trueExample: includeDeltas=false

raw

boolean

default:"false"

Include raw SSE lines in the rawEvents field of the response.Default: falseExample: raw=true

Response Fields

runId

string

The run identifier.

chatId

string

The chat thread UUID for this run.

status

string

Current external status: queued, running, completed, failed, cancelled, or interrupted.

source

string

Where the events came from: "buffer" (live in-memory), "reconstructed" (from DB), or "merged".

eventCount

number

Total number of events returned.

events

array

Array of parsed event objects.

Show Event Object

type

string

Event type. Common values:

text-start — beginning of a text block
text-delta — incremental text chunk
tool-call-start — agent started a tool call
tool-input-available — tool call input is ready
tool-output-available — tool call result is ready
task-files — files produced by the task
finish — task completed
error — task failed

string

Event or message identifier (present on text events).

delta

string

Text chunk content (present on text-delta events).

toolCallId

string

Tool call identifier (present on tool events).

toolName

string

Name of the tool called (present on tool events).

input

object

Tool call input (present on tool-input-available).

output

object

Tool call result (present on tool-output-available).

error

string | null

Error message if the run failed, null otherwise.

rawEvents

array

Raw SSE lines (only present when raw=true).

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

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "chatId": "chat_def789ghi012",
  "status": "completed",
  "source": "reconstructed",
  "eventCount": 5,
  "events": [
    {
      "type": "text-start",
      "id": "msg_abc123"
    },
    {
      "type": "tool-call-start",
      "toolCallId": "tc_001",
      "toolName": "bash"
    },
    {
      "type": "tool-input-available",
      "toolCallId": "tc_001",
      "toolName": "bash",
      "input": { "command": "ls -la /vercel/sandbox" }
    },
    {
      "type": "tool-output-available",
      "toolCallId": "tc_001",
      "toolName": "bash",
      "output": { "stdout": "total 8\ndrwxr-xr-x 2 root root 4096 ...", "exitCode": 0 }
    },
    {
      "type": "finish",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed"
    }
  ],
  "error": null
}

Error Codes

Status Code	Error	Description
200	Success	Logs retrieved successfully
401	Unauthorized	Invalid or missing API key
403	Forbidden	Task belongs to a different user
404	Not Found	Task not found
500	Internal Server Error	Failed to fetch logs

Cancel Task Stream Task Logs

​Authentication

​Headers

​Path Parameters

​Query Parameters

​Response Fields

​Error Codes

Authentication

Headers

Path Parameters

Query Parameters

Response Fields

Error Codes