Skip to main content
GET
https://cloud.blackbox.ai
/
api
/
tasks
/
{taskId}
curl 'https://cloud.blackbox.ai/api/tasks/9qQe2F8Z_nXx9-eJA0BD6' \
  -H 'Authorization: Bearer bb_YOUR_API_KEY' \
  -H 'Accept: application/json'

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

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0

​
Path Parameters

​
taskId
string
required
The unique identifier of the task you want to retrieve.Example: 9qQe2F8Z_nXx9-eJA0BD6

​
Response Fields

​
Task Object

​
id
string
Unique identifier for the task.
​
userId
string
Email or ID of the user who created the task.
​
prompt
string
The original task description or instruction provided.
​
repoUrl
string
GitHub repository URL the task was executed on.
​
selectedAgent
string
The AI agent used for executing the task (claude, blackbox, codex, gemini).
​
selectedModel
string
The specific AI model used with the selected agent.
​
status
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
​
progress
number
Task completion percentage (0-100).
​
logs
array
Array of log entries generated during task execution.
​
selectedBranch
string
The branch that was worked on in the repository.
​
branchName
string
The new branch name created for the task changes.
​
sandboxId
string
Identifier for the sandbox environment used for execution.
​
merged
boolean
Whether the changes have been merged into the target branch.
​
prNumber
number
Pull request number if a PR was created (null otherwise).
​
prUrl
string
URL to the pull request if created.
​
multiLaunch
boolean
Whether multiple agents were launched for this task.
​
selectedAgents
array
Array of agent configurations when using multi-launch mode.Each object contains:
  • agent - Agent name
  • model - Model identifier
​
agentExecutions
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
​
diffAnalysis
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
​
diffStats
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
​
cumulativeDiff
string
Complete git diff of all changes made across all agents.
​
checkpoint
object
Checkpoint information for each agent’s execution stage.
​
error
string
Error message if the task failed (null otherwise).
​
createdAt
string
ISO 8601 timestamp when the task was created.
​
updatedAt
string
ISO 8601 timestamp when the task was last updated.
​
completedAt
string
ISO 8601 timestamp when the task completed (null if still running).
​
isPublic
boolean
Whether the task is publicly accessible.
curl 'https://cloud.blackbox.ai/api/tasks/9qQe2F8Z_nXx9-eJA0BD6' \
  -H 'Authorization: Bearer bb_YOUR_API_KEY' \
  -H 'Accept: application/json'

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

​
Use Cases

​
Polling for Task Completion

You can poll this endpoint to monitor task progress: 
async function waitForTaskCompletion(taskId) {
  const API_KEY = "bb_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: 
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: 
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 CodeErrorDescription
200SuccessTask details retrieved successfully
401UnauthorizedInvalid or missing API key
404Not FoundTask not found or user does not have access to the task
500Internal Server ErrorDatabase error occurred while fetching task