Get Task

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}

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:

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

Response Fields

taskIdstring

Unique identifier for the task (same as runId).

runIdstring

Unique identifier for this agent run.

chatIdstring

UUID of the chat thread this run belongs to.

statusstring

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

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

assistantMessageIdstring | null

ID of the assistant message being generated.

createdAtstring

ISO 8601 timestamp when the run was created.

startedAtstring | null

ISO 8601 timestamp when the run started executing.

completedAtstring | null

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

errorstring | null

Error message if the run failed, null otherwise.

githubobject

GitHub context for the task.

GitHub Object

repoUrlstring | null

Full GitHub repository URL.

ownerstring | null

Repository owner (org or user).

repostring | null

Repository name.

baseBranchstring | null

The branch the agent started from.

createdBranchstring | null

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

messagesarray

Full conversation history for this task's chat thread.

Message Object

idstring

Unique message identifier.

rolestring

Message role: "user" or "assistant".

partsarray

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

createdAtstring

ISO 8601 timestamp when the message was created.

inMemoryobject | null

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

inMemory Object

statusstring

Live status from in-memory store.

startedAtstring | null

Live startedAt timestamp.

completedAtstring | null

Live completedAt timestamp.

Request Example

curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -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}`,
  { 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}`);

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']}")

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"])
}

Response Example

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

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

{
  "error": "Task not found"
}

{
  "error": "Forbidden"
}

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