Skip to main content
GET
/
api
/
v1
/
tasks
/
{runId}
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "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.
​
messages
array
Full conversation history for this task’s chat thread.
​
inMemory
object | null
Live in-memory state. null if the server has restarted since the run was created.
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "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 CodeErrorDescription
200SuccessTask details retrieved successfully
401UnauthorizedInvalid or missing API key
403ForbiddenTask belongs to a different user
404Not FoundTask not found
500Internal Server ErrorDatabase error