Get Task Logs

Retrieve the full execution log for a task as parsed stream events. For live tasks, events come from the in-memory buffer. For completed tasks, events are reconstructed from persisted message parts.

GET /api/v1/tasks/{runId}/logs

cURL

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

Success Response

{
  "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:

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

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: true

Example: includeDeltas=false

raw · boolean · default: "false"

Include raw SSE lines in the rawEvents field of the response.

Default: false

Example: 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

id · 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

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

Success Response

{
  "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