> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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](https://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](https://app.blackbox.ai/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

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

## Path Parameters

<ParamField path="runId" type="string" required>
  The unique run identifier returned when the task was created.

  Example: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

## Query Parameters

<ParamField query="includeDeltas" type="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`
</ParamField>

<ParamField query="raw" type="boolean" default="false">
  Include raw SSE lines in the `rawEvents` field of the response.

  Default: `false`

  Example: `raw=true`
</ParamField>

## Response Fields

<ResponseField name="runId" type="string">
  The run identifier.
</ResponseField>

<ResponseField name="chatId" type="string">
  The chat thread UUID for this run.
</ResponseField>

<ResponseField name="status" type="string">
  Current external status: `queued`, `running`, `completed`, `failed`, `cancelled`, or `interrupted`.
</ResponseField>

<ResponseField name="source" type="string">
  Where the events came from: `"buffer"` (live in-memory), `"reconstructed"` (from DB), or `"merged"`.
</ResponseField>

<ResponseField name="eventCount" type="number">
  Total number of events returned.
</ResponseField>

<ResponseField name="events" type="array">
  Array of parsed event objects.

  <Expandable title="Event Object">
    <ResponseField name="type" 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
    </ResponseField>

    <ResponseField name="id" type="string">
      Event or message identifier (present on text events).
    </ResponseField>

    <ResponseField name="delta" type="string">
      Text chunk content (present on `text-delta` events).
    </ResponseField>

    <ResponseField name="toolCallId" type="string">
      Tool call identifier (present on tool events).
    </ResponseField>

    <ResponseField name="toolName" type="string">
      Name of the tool called (present on tool events).
    </ResponseField>

    <ResponseField name="input" type="object">
      Tool call input (present on `tool-input-available`).
    </ResponseField>

    <ResponseField name="output" type="object">
      Tool call result (present on `tool-output-available`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the run failed, `null` otherwise.
</ResponseField>

<ResponseField name="rawEvents" type="array">
  Raw SSE lines (only present when `raw=true`).
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash cURL - No Deltas theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs?includeDeltas=false' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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}`));
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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
  }
  ```

  ```json Error - Not Found theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Task not found"
  }
  ```
</ResponseExample>

## 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             |