Get Task

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

GET /api/v1/tasks/{runId}

cURL

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

Success Response - Completed Task

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

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

Response Fields

taskId · string

Unique identifier for the task (same as runId).

runId · string

Unique identifier for this agent run.

chatId · string

UUID of the chat thread this run belongs to.

status · string

Current status of the run. Reflects live in-memory state when available.

Possible values: queued, running, completed, failed, cancelled, interrupted

assistantMessageId · string | null

ID of the assistant message being generated.

createdAt · string

ISO 8601 timestamp when the run was created.

startedAt · string | null

ISO 8601 timestamp when the run started executing.

completedAt · string | null

ISO 8601 timestamp when the run completed. null if still running.

error · string | null

Error message if the run failed, null otherwise.

github · object

GitHub context for the task.

Show GitHub Object

repoUrl · string | null

Full GitHub repository URL.

owner · string | null

Repository owner (org or user).

repo · string | null

Repository name.

baseBranch · string | null

The branch the agent started from.

createdBranch · string | null

The new branch created by the agent (if any).

messages · array

Full conversation history for this task’s chat thread.

Show Message Object

id · string

Unique message identifier.

role · string

Message role: "user" or "assistant".

parts · array

Message content parts (e.g. [{ "type": "text", "text": "..." }]).

createdAt · string

ISO 8601 timestamp when the message was created.

inMemory · object | null

Live in-memory state. null if the server has restarted since the run was created.

Show inMemory Object

status · string

Live status from in-memory store.

startedAt · string | null

Live startedAt timestamp.

completedAt · string | null

Live completedAt timestamp.

cURL

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

Success Response - Completed Task

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

Use Cases

Poll Until Completion

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

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