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

> Retrieve full details of a specific agent task run, including status, GitHub context, and the complete conversation message history.

This endpoint returns comprehensive details about a task run. It merges live in-memory state (for running tasks) with persisted database records, giving you the most up-to-date information available.

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

## Response Fields

<ResponseField name="taskId" type="string">
  Unique identifier for the task (same as `runId`).
</ResponseField>

<ResponseField name="runId" type="string">
  Unique identifier for this agent run.
</ResponseField>

<ResponseField name="chatId" type="string">
  UUID of the chat thread this run belongs to.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the run. Reflects live in-memory state when available.

  Possible values: `queued`, `running`, `completed`, `failed`, `cancelled`, `interrupted`
</ResponseField>

<ResponseField name="assistantMessageId" type="string | null">
  ID of the assistant message being generated.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the run was created.
</ResponseField>

<ResponseField name="startedAt" type="string | null">
  ISO 8601 timestamp when the run started executing.
</ResponseField>

<ResponseField name="completedAt" type="string | null">
  ISO 8601 timestamp when the run completed. `null` if still running.
</ResponseField>

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

<ResponseField name="github" type="object">
  GitHub context for the task.

  <Expandable title="GitHub Object">
    <ResponseField name="repoUrl" type="string | null">
      Full GitHub repository URL.
    </ResponseField>

    <ResponseField name="owner" type="string | null">
      Repository owner (org or user).
    </ResponseField>

    <ResponseField name="repo" type="string | null">
      Repository name.
    </ResponseField>

    <ResponseField name="baseBranch" type="string | null">
      The branch the agent started from.
    </ResponseField>

    <ResponseField name="createdBranch" type="string | null">
      The new branch created by the agent (if any).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="messages" type="array">
  Full conversation history for this task's chat thread.

  <Expandable title="Message Object">
    <ResponseField name="id" type="string">
      Unique message identifier.
    </ResponseField>

    <ResponseField name="role" type="string">
      Message role: `"user"` or `"assistant"`.
    </ResponseField>

    <ResponseField name="parts" type="array">
      Message content parts (e.g. `[{ "type": "text", "text": "..." }]`).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the message was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="inMemory" type="object | null">
  Live in-memory state. `null` if the server has restarted since the run was created.

  <Expandable title="inMemory Object">
    <ResponseField name="status" type="string">
      Live status from in-memory store.
    </ResponseField>

    <ResponseField name="startedAt" type="string | null">
      Live startedAt timestamp.
    </ResponseField>

    <ResponseField name="completedAt" type="string | null">
      Live completedAt timestamp.
    </ResponseField>
  </Expandable>
</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' \
    -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}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  console.log(`Status: ${data.status}`);
  console.log(`Branch created: ${data.github.createdBranch}`);
  console.log(`Messages: ${data.messages.length}`);
  ```

  ```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}",
      headers={"Authorization": f"Bearer {API_KEY}"},
  )
  data = response.json()
  print(f"Status: {data['status']}")
  print(f"Branch: {data['github']['createdBranch']}")
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  package main

  import (
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      runId := "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      url := fmt.Sprintf("https://agent.blackbox.ai/api/v1/tasks/%s", runId)

      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("Authorization", "Bearer "+apiKey)

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      body, _ := io.ReadAll(resp.Body)
      var result map[string]interface{}
      json.Unmarshal(body, &result)
      fmt.Println(result["status"])
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response - Completed Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chatId": "chat_def789ghi012",
    "status": "completed",
    "assistantMessageId": "msg_abc123xyz456",
    "createdAt": "2026-05-19T10:00:00.000Z",
    "startedAt": "2026-05-19T10:00:02.000Z",
    "completedAt": "2026-05-19T10:04:45.000Z",
    "error": null,
    "github": {
      "repoUrl": "https://github.com/my-org/my-repo.git",
      "owner": "my-org",
      "repo": "my-repo",
      "baseBranch": "main",
      "createdBranch": "feature/add-readme-fr-a1b2"
    },
    "messages": [
      {
        "id": "msg_user_001",
        "role": "user",
        "parts": [{ "type": "text", "text": "Add a README in French" }],
        "createdAt": "2026-05-19T10:00:00.500Z"
      },
      {
        "id": "msg_abc123xyz456",
        "role": "assistant",
        "parts": [{ "type": "text", "text": "I've created a README.fr.md file..." }],
        "createdAt": "2026-05-19T10:04:44.000Z"
      }
    ],
    "inMemory": null
  }
  ```

  ```json Success Response - Running Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "runId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "chatId": "chat_ghi012jkl345",
    "status": "running",
    "assistantMessageId": "msg_def456uvw789",
    "createdAt": "2026-05-19T10:10:00.000Z",
    "startedAt": "2026-05-19T10:10:01.000Z",
    "completedAt": null,
    "error": null,
    "github": {
      "repoUrl": null,
      "owner": null,
      "repo": null,
      "baseBranch": null,
      "createdBranch": null
    },
    "messages": [
      {
        "id": "msg_user_002",
        "role": "user",
        "parts": [{ "type": "text", "text": "Write a Python script to parse CSV files" }],
        "createdAt": "2026-05-19T10:10:00.500Z"
      }
    ],
    "inMemory": {
      "status": "running",
      "startedAt": "2026-05-19T10:10:01.000Z",
      "completedAt": null
    }
  }
  ```

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

  ```json Error - Forbidden theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Forbidden"
  }
  ```
</ResponseExample>

## Use Cases

### Poll Until Completion

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
async function waitForTask(runId, apiKey) {
  const url = `https://agent.blackbox.ai/api/v1/tasks/${runId}`;

  while (true) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const data = await res.json();

    console.log(`Status: ${data.status}`);

    if (["completed", "failed", "cancelled", "interrupted"].includes(data.status)) {
      return data;
    }

    await new Promise(r => setTimeout(r, 3000));
  }
}
```

### Extract the Agent's Response

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const data = await response.json();

const assistantMessages = data.messages.filter(m => m.role === "assistant");
const lastReply = assistantMessages.at(-1);
const text = lastReply?.parts?.find(p => p.type === "text")?.text ?? "";
console.log("Agent reply:", text);
```

## Error Codes

| Status Code | Error                 | Description                         |
| ----------- | --------------------- | ----------------------------------- |
| 200         | Success               | Task details 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 | Database error                      |