Authentication
To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:- Click on your Profile Image in the top right corner at cloud.blackbox.ai
- Click on “BLACKBOX API Token” from the dropdown menu
- Copy the existing token or click “Generate” if you don’t have one yet
bb_xxxxxxxxxxxxxxxxxxxxxx
Headers
API Key of the form
Bearer <api_key>.Example: Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0Path Parameters
The unique identifier of the task you want to retrieve.Example:
9qQe2F8Z_nXx9-eJA0BD6Response Fields
Task Object
Unique identifier for the task.
Email or ID of the user who created the task.
The original task description or instruction provided.
GitHub repository URL the task was executed on (null for standalone prompts).
The AI agent used for executing the task (claude, blackbox, codex, gemini).
The specific AI model used with the selected agent.
Current status of the task.Possible values:
pending- Task is queued and waiting to startrunning- Task is currently being executedcompleted- Task finished successfullyfailed- Task encountered an errorcancelled- Task was cancelled by user
Task completion percentage (0-100).
Array of log entries generated during task execution.
The branch that was worked on in the repository.
The new branch name created for the task changes.
Identifier for the sandbox environment used for execution.
Whether the changes have been merged into the target branch.
Pull request number if a PR was created (null otherwise).
URL to the pull request if created.
Whether multiple agents were launched for this task.
Array of agent configurations when using multi-launch mode.Each object contains:
agent- Agent namemodel- Model identifier
Detailed execution information for each agent in multi-launch mode.Each object contains:
agent- Agent namestatus- Execution statusgitDiff- Git diff of changes madebranchName- Branch created by this agentexecutedAt- Execution start timestampcompletedAt- Execution completion timestamp
Analysis comparing different agent implementations (for multi-launch tasks).Contains:
analysis- Detailed markdown analysis of implementationsbestAgent- Name of the agent with the best implementationanalyzedAt- Timestamp of analysis
Statistics about code changes made.Contains:
totalLinesAdded- Number of lines addedtotalLinesRemoved- Number of lines removedtotalFilesChanged- Number of files modifiedinitialCommitSha- SHA of the initial commit
Complete git diff of all changes made across all agents.
Checkpoint information for each agent’s execution stage.
Error message if the task failed (null otherwise).
ISO 8601 timestamp when the task was created.
ISO 8601 timestamp when the task was last updated.
ISO 8601 timestamp when the task completed (null if still running).
Whether the task is publicly accessible.
Use Cases
Polling for Task Completion
You can poll this endpoint to monitor task progress:Analyzing Multi-Agent Results
For tasks withmultiLaunch: true, you can compare different agent implementations: