Get Task Logs

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}/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.

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

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query Parameters

includeDeltasbooleandefault: true

Whether to include text-delta events (individual text chunks). Set to false for a smaller, summarized payload.

Default: true

Example: includeDeltas=false

rawbooleandefault: false

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

Default: false

Example: raw=true

Response Fields

runIdstring

The run identifier.

chatIdstring

The chat thread UUID for this run.

statusstring

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

sourcestring

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

eventCountnumber

Total number of events returned.

eventsarray

Array of parsed event objects.

Event Object

typestring

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

idstring

Event or message identifier (present on text events).

deltastring

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

toolCallIdstring

Tool call identifier (present on tool events).

toolNamestring

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

inputobject

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

outputobject

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

errorstring | null

Error message if the run failed, null otherwise.

rawEventsarray

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

Request Example

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

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

const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const response = await fetch(
  `https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/logs?includeDeltas=false`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const data = await response.json();
console.log(`Source: ${data.source}, Events: ${data.eventCount}`);

// Print tool calls
data.events
  .filter(e => e.type === "tool-call-start")
  .forEach(e => console.log(`Tool: ${e.toolName}`));

import requests

API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/logs",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"includeDeltas": "false"},
)
data = response.json()
print(f"Source: {data['source']}, Events: {data['eventCount']}")

for event in data["events"]:
    if event["type"] == "tool-call-start":
        print(f"Tool called: {event['toolName']}")

Response Example

{
  "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": "Task not found"
}

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