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

> Retrieve detailed information about a specific task including status, progress, logs, and execution results.

This endpoint allows you to retrieve comprehensive details about a task that has been created. You can monitor task progress, view execution logs, analyze diffs, and check completion status.

## Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

1. **Click on your Profile Image** in the top right corner at [cloud.blackbox.ai](https://cloud.blackbox.ai)
2. **Click on "BLACKBOX API Token"** from the dropdown menu
3. **Copy the existing token** or **click "Generate"** if you don't have one yet

Your API key will be in the format: `bb_xxxxxxxxxxxxxxxxxxxxxx`

## Headers

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

  Example: `Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0`
</ParamField>

## Path Parameters

<ParamField path="taskId" type="string" required>
  The unique identifier of the task you want to retrieve.

  Example: `9qQe2F8Z_nXx9-eJA0BD6`
</ParamField>

## Response Fields

### Task Object

<ResponseField name="id" type="string">
  Unique identifier for the task.
</ResponseField>

<ResponseField name="userId" type="string">
  Email or ID of the user who created the task.
</ResponseField>

<ResponseField name="prompt" type="string">
  The original task description or instruction provided.
</ResponseField>

<ResponseField name="repoUrl" type="string">
  GitHub repository URL the task was executed on.
</ResponseField>

<ResponseField name="selectedAgent" type="string">
  The AI agent used for executing the task (claude, blackbox, codex, gemini).
</ResponseField>

<ResponseField name="selectedModel" type="string">
  The specific AI model used with the selected agent.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the task.

  Possible values:

  * `pending` - Task is queued and waiting to start
  * `running` - Task is currently being executed
  * `completed` - Task finished successfully
  * `failed` - Task encountered an error
  * `cancelled` - Task was cancelled by user
</ResponseField>

<ResponseField name="progress" type="number">
  Task completion percentage (0-100).
</ResponseField>

<ResponseField name="logs" type="array">
  Array of log entries generated during task execution.
</ResponseField>

<ResponseField name="selectedBranch" type="string">
  The branch that was worked on in the repository.
</ResponseField>

<ResponseField name="branchName" type="string">
  The new branch name created for the task changes.
</ResponseField>

<ResponseField name="sandboxId" type="string">
  Identifier for the sandbox environment used for execution.
</ResponseField>

<ResponseField name="merged" type="boolean">
  Whether the changes have been merged into the target branch.
</ResponseField>

<ResponseField name="prNumber" type="number">
  Pull request number if a PR was created (null otherwise).
</ResponseField>

<ResponseField name="prUrl" type="string">
  URL to the pull request if created.
</ResponseField>

<ResponseField name="multiLaunch" type="boolean">
  Whether multiple agents were launched for this task.
</ResponseField>

<ResponseField name="selectedAgents" type="array">
  Array of agent configurations when using multi-launch mode.

  Each object contains:

  * `agent` - Agent name
  * `model` - Model identifier
</ResponseField>

<ResponseField name="agentExecutions" type="array">
  Detailed execution information for each agent in multi-launch mode.

  Each object contains:

  * `agent` - Agent name
  * `status` - Execution status
  * `gitDiff` - Git diff of changes made
  * `branchName` - Branch created by this agent
  * `executedAt` - Execution start timestamp
  * `completedAt` - Execution completion timestamp
</ResponseField>

<ResponseField name="diffAnalysis" type="object">
  Analysis comparing different agent implementations (for multi-launch tasks).

  Contains:

  * `analysis` - Detailed markdown analysis of implementations
  * `bestAgent` - Name of the agent with the best implementation
  * `analyzedAt` - Timestamp of analysis
</ResponseField>

<ResponseField name="diffStats" type="object">
  Statistics about code changes made.

  Contains:

  * `totalLinesAdded` - Number of lines added
  * `totalLinesRemoved` - Number of lines removed
  * `totalFilesChanged` - Number of files modified
  * `initialCommitSha` - SHA of the initial commit
</ResponseField>

<ResponseField name="cumulativeDiff" type="string">
  Complete git diff of all changes made across all agents.
</ResponseField>

<ResponseField name="checkpoint" type="object">
  Checkpoint information for each agent's execution stage.
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the task failed (null otherwise).
</ResponseField>

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

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when the task was last updated.
</ResponseField>

<ResponseField name="completedAt" type="string">
  ISO 8601 timestamp when the task completed (null if still running).
</ResponseField>

<ResponseField name="isPublic" type="boolean">
  Whether the task is publicly accessible.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://cloud.blackbox.ai/api/tasks/9qQe2F8Z_nXx9-eJA0BD6' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Accept: application/json'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const API_KEY = "YOUR_API_KEY";
  const TASK_ID = "9qQe2F8Z_nXx9-eJA0BD6";
  const API_URL = `https://cloud.blackbox.ai/api/tasks/${TASK_ID}`;

  const response = await fetch(API_URL, {
      method: "GET",
      headers: {
          Authorization: `Bearer ${API_KEY}`,
          Accept: "application/json",
      },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  API_KEY = "YOUR_API_KEY"
  TASK_ID = "9qQe2F8Z_nXx9-eJA0BD6"
  API_URL = f"https://cloud.blackbox.ai/api/tasks/{TASK_ID}"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Accept": "application/json"
  }

  response = requests.get(API_URL, headers=headers)
  print(response.json())
  ```

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

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

  func main() {
      apiKey := "YOUR_API_KEY"
      taskId := "9qQe2F8Z_nXx9-eJA0BD6"
      url := fmt.Sprintf("https://cloud.blackbox.ai/api/tasks/%s", taskId)

      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))
      req.Header.Add("Accept", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := io.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response - Completed Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "task": {
      "id": "9qQe2F8Z_nXx9-eJA0BD6",
      "userId": "user@example.com",
      "teamId": null,
      "prompt": "Add Stripe payment gateway",
      "repoUrl": "https://github.com/username/repository.git",
      "selectedAgent": "claude",
      "selectedModel": "claude-sonnet-4.5",
      "installDependencies": false,
      "maxDuration": 300,
      "keepAlive": true,
      "status": "completed",
      "progress": 100,
      "logs": [],
      "followupMessages": null,
      "checkpoint": {
        "claude": {
          "stage": "diff_analyzed",
          "timestamp": "2025-11-20T23:41:36.930Z"
        },
        "blackbox": {
          "stage": "diff_analyzed",
          "timestamp": "2025-11-20T23:41:37.051Z"
        }
      },
      "error": null,
      "selectedBranch": "main",
      "branchName": "feature/add-stripe-payment-j6k-claude",
      "sandboxUrl": null,
      "sandboxId": "sbx_XJV19Afr0gXFrc723Asn2bfSb3H8",
      "agentSandboxConfig": {
        "claude": {
          "sandboxId": "sbx_XJV19Afr0gXFrc723Asn2bfSb3H8",
          "branchName": "feature/add-stripe-payment-j6k-claude"
        }
      },
      "merged": false,
      "prNumber": null,
      "prUrl": null,
      "multiLaunch": true,
      "selectedAgents": [
        {
          "agent": "claude",
          "model": "claude-sonnet-4.5"
        },
        {
          "agent": "blackbox",
          "model": "blackbox-pro"
        }
      ],
      "agentExecutions": [
        {
          "agent": "claude",
          "status": "completed",
          "gitDiff": "diff --git a/src/payment/stripe.ts b/src/payment/stripe.ts\nnew file mode 100644\nindex 0000000..1234567\n--- /dev/null\n+++ b/src/payment/stripe.ts\n@@ -0,0 +1,85 @@\n+import Stripe from 'stripe';\n+\n+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);\n+...",
          "branchName": "feature/add-stripe-payment-j6k-claude",
          "executedAt": "2025-11-20T23:37:24.186Z",
          "completedAt": "2025-11-20T23:39:43.833Z"
        },
        {
          "agent": "blackbox",
          "status": "completed",
          "gitDiff": "diff --git a/src/services/payment.ts b/src/services/payment.ts\nnew file mode 100644\nindex 0000000..7890abc\n--- /dev/null\n+++ b/src/services/payment.ts\n@@ -0,0 +1,92 @@\n+const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);\n+...",
          "branchName": "feature/add-stripe-payment-j6k-blackbox",
          "executedAt": "2025-11-20T23:37:24.186Z",
          "completedAt": "2025-11-20T23:41:11.258Z"
        }
      ],
      "diffAnalysis": {
        "analysis": "# Best Implementation: CLAUDE\n\n## Analysis Reasoning\n\nClaude's implementation demonstrates superior understanding of Stripe integration best practices. The code uses TypeScript with proper type definitions, implements error handling, and follows modern ES6+ patterns. The implementation includes webhook handling, proper environment variable management, and comprehensive payment flow coverage including checkout sessions, payment intents, and subscription management.\n\n## Detailed Agent Analysis\n\n### CLAUDE (Winner)\n\n**Score:** 9/10\n\n**Strengths:**\n- Uses TypeScript with proper Stripe type definitions\n- Implements comprehensive error handling and logging\n- Follows modern ES6+ module patterns\n- Includes webhook signature verification\n- Proper environment variable management\n- Implements both one-time payments and subscriptions\n- Clean separation of concerns with service layer\n\n**Weaknesses:**\n- Could benefit from additional unit tests\n- Missing some edge case handling for refunds\n\n---\n\n### BLACKBOX\n\n**Score:** 7/10\n\n**Strengths:**\n- Complete Stripe integration implementation\n- Includes basic error handling\n- Covers essential payment flows\n- Functional webhook implementation\n\n**Weaknesses:**\n- Uses CommonJS instead of ES6 modules\n- Lacks TypeScript type safety\n- Less comprehensive error handling\n- Missing some advanced Stripe features\n\n---\n\n## Conclusion\n\nClaude's implementation wins due to its use of TypeScript, superior error handling, and adherence to modern JavaScript best practices. The implementation is production-ready with proper type safety and comprehensive coverage of Stripe payment flows.",
        "bestAgent": "claude",
        "analyzedAt": "2025-11-20T23:41:36.810Z"
      },
      "diffStats": {
        "totalLinesAdded": 247,
        "initialCommitSha": "dcee312deecf502c5a161d9067bf974dd9874bcf",
        "totalFilesChanged": 4,
        "totalLinesRemoved": 12
      },
      "cumulativeDiff": "diff --git a/src/payment/stripe.ts b/src/payment/stripe.ts\nnew file mode 100644\nindex 0000000..1234567\n--- /dev/null\n+++ b/src/payment/stripe.ts\n@@ -0,0 +1,85 @@\n+import Stripe from 'stripe';\n+\n+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);\n+...",
      "taskSource": "manual",
      "scheduledTaskId": null,
      "repoInstructions": null,
      "environmentVariables": null,
      "testAccounts": null,
      "autoDeployEnabled": false,
      "deploymentProvider": "vercel",
      "vercelDeploymentSettings": null,
      "gcloudDeploymentSettings": null,
      "deployments": null,
      "lock": null,
      "createdAt": "2025-11-20T23:37:17.761Z",
      "updatedAt": "2025-11-20T23:41:39.024Z",
      "completedAt": "2025-11-20T23:41:39.024Z",
      "slackUserId": null,
      "slackTeamId": null,
      "slackChannelId": null,
      "slackMessageTs": null,
      "badge": null,
      "batchId": null,
      "isPublic": false,
      "isEmptyGitUser": false,
      "metaData": null
    }
  }
  ```

  ```json Success Response - Running Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "task": {
      "id": "abc123xyz456",
      "userId": "user@example.com",
      "teamId": null,
      "prompt": "Add unit tests for authentication module",
      "repoUrl": "https://github.com/username/repository.git",
      "selectedAgent": "blackbox",
      "selectedModel": "blackbox-pro",
      "installDependencies": false,
      "maxDuration": 300,
      "keepAlive": false,
      "status": "running",
      "progress": 45,
      "logs": [
        "Cloning repository...",
        "Analyzing codebase...",
        "Generating test cases..."
      ],
      "followupMessages": null,
      "checkpoint": {
        "blackbox": {
          "stage": "executing",
          "timestamp": "2025-11-21T10:15:30.123Z"
        }
      },
      "error": null,
      "selectedBranch": "main",
      "branchName": "tests/add-auth-tests-xyz",
      "sandboxUrl": null,
      "sandboxId": "sbx_ABC123XYZ456",
      "agentSandboxConfig": null,
      "merged": false,
      "prNumber": null,
      "prUrl": null,
      "multiLaunch": false,
      "selectedAgents": null,
      "agentExecutions": null,
      "diffAnalysis": null,
      "diffStats": null,
      "cumulativeDiff": null,
      "taskSource": "manual",
      "scheduledTaskId": null,
      "repoInstructions": null,
      "environmentVariables": null,
      "testAccounts": null,
      "autoDeployEnabled": false,
      "deploymentProvider": "vercel",
      "vercelDeploymentSettings": null,
      "gcloudDeploymentSettings": null,
      "deployments": null,
      "lock": null,
      "createdAt": "2025-11-21T10:10:00.000Z",
      "updatedAt": "2025-11-21T10:15:30.123Z",
      "completedAt": null,
      "slackUserId": null,
      "slackTeamId": null,
      "slackChannelId": null,
      "slackMessageTs": null,
      "badge": null,
      "batchId": null,
      "isPublic": false,
      "isEmptyGitUser": false,
      "metaData": null
    }
  }
  ```

  ```json Error Response - Task Not Found theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Task not found",
    "message": "No task found with ID: invalid_task_id",
    "status": 404
  }
  ```

  ```json Error Response - Unauthorized theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
  ```
</ResponseExample>

## Use Cases

### Polling for Task Completion

You can poll this endpoint to monitor task progress:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
async function waitForTaskCompletion(taskId) {
  const API_KEY = "YOUR_API_KEY";
  const API_URL = `https://cloud.blackbox.ai/api/tasks/${taskId}`;
  
  while (true) {
    const response = await fetch(API_URL, {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        Accept: "application/json",
      },
    });
    
    const { task } = await response.json();
    
    console.log(`Status: ${task.status}, Progress: ${task.progress}%`);
    
    if (task.status === "completed" || task.status === "failed") {
      return task;
    }
    
    // Wait 5 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}
```

### Analyzing Multi-Agent Results

For tasks with `multiLaunch: true`, you can compare different agent implementations:

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

if (task.multiLaunch && task.diffAnalysis) {
  console.log("Best Agent:", task.diffAnalysis.bestAgent);
  console.log("Analysis:", task.diffAnalysis.analysis);
  
  task.agentExecutions.forEach(execution => {
    console.log(`\n${execution.agent}:`);
    console.log(`  Status: ${execution.status}`);
    console.log(`  Branch: ${execution.branchName}`);
    console.log(`  Duration: ${
      new Date(execution.completedAt) - new Date(execution.executedAt)
    }ms`);
  });
}
```

### Retrieving Code Changes

Access the git diff to see what changes were made:

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

if (task.status === "completed") {
  console.log("Files Changed:", task.diffStats.totalFilesChanged);
  console.log("Lines Added:", task.diffStats.totalLinesAdded);
  console.log("Lines Removed:", task.diffStats.totalLinesRemoved);
  console.log("\nFull Diff:\n", task.cumulativeDiff);
}
```

## Error Codes

| Status Code | Error                 | Description                                             |
| ----------- | --------------------- | ------------------------------------------------------- |
| 200         | Success               | Task details retrieved successfully                     |
| 401         | Unauthorized          | Invalid or missing API key                              |
| 404         | Not Found             | Task not found or user does not have access to the task |
| 500         | Internal Server Error | Database error occurred while fetching task             |