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

# Continue an Agent Task

> Send a follow-up prompt to an existing task, continuing the agent's work with new instructions or additional context.

This endpoint allows you to continue an existing task by sending a follow-up prompt. The agent will pick up where it left off, applying your new instructions to the same repository and branch.

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

## GitHub Connection Required

<Note>
  **For GitHub-related tasks**: Make sure you have connected your GitHub account on [https://cloud.blackbox.ai](https://cloud.blackbox.ai) before continuing tasks that work with repositories. This is required for the agent to access and modify your repositories.
</Note>

## Headers

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

  Example: `Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

## Path Parameters

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

  Example: `ac2wbk3lXAufdSdIscsirg`
</ParamField>

## Request Parameters

<ParamField body="currentPrompt" type="string" required>
  The follow-up instruction or message for the agent. This is appended to the task's history so the agent has full context of prior work.

  Examples:

  * `"Also add unit tests for the new payment module"`
  * `"The Stripe webhook handler is missing error handling, please fix it"`
  * `"Summarize what was done so far"`
</ParamField>

<ParamField body="selectedAgent" type="string">
  Override the agent for this follow-up. If omitted, the task's original agent is used.

  Available agents: `claude`, `blackbox`, `codex`, `gemini`, `blackbox-grok`
</ParamField>

<ParamField body="selectedModel" type="string">
  Override the model for this follow-up. If omitted, the task's original model is used.

  Example: `blackboxai/blackbox-pro`, `blackboxai/anthropic/claude-sonnet-4.5`
</ParamField>

<ParamField body="maxDuration" type="number">
  Maximum execution time in seconds for this follow-up. Defaults to the original task's `maxDuration`.
</ParamField>

<ParamField body="keepAlive" type="boolean">
  Whether to keep the sandbox alive after this follow-up completes. Defaults to `false`.
</ParamField>

<ParamField body="installDependencies" type="boolean">
  Whether to run dependency installation before executing this follow-up. Defaults to `false`.
</ParamField>

<ParamField body="environmentVariables" type="string">
  Environment variables to inject into the sandbox for this follow-up, as a newline-separated `KEY=VALUE` string.

  Example: `"STRIPE_KEY=sk_test_xxx\nNODE_ENV=production"`
</ParamField>

<ParamField body="globalInstructions" type="string">
  Additional system-level instructions to prepend to the agent's context for this follow-up.
</ParamField>

<ParamField body="multiLaunch" type="boolean">
  Set to `true` to run this follow-up across multiple agents in parallel. Requires `selectedAgents`.
</ParamField>

<ParamField body="selectedAgents" type="array">
  Array of agent configurations for multi-agent follow-up mode. Required when `multiLaunch` is `true`.

  **Structure**: Each object must contain:

  * `agent` (string, required): The agent type
  * `model` (string, required): The specific model to use

  **Minimum**: 2 agents when `multiLaunch` is `true`
</ParamField>

## How Task Continuation Works

1. **Follow-up stored**: Your `currentPrompt` is appended to the task's `followupMessages` array
2. **Context rebuilt**: The agent receives the full history of prior prompts and outputs as context
3. **Sandbox resumed**: A new sandbox is created (or reused) from the task's existing branch
4. **Agent executes**: The agent applies your new instructions on top of prior work
5. **Changes committed**: Any new changes are committed to the same branch
6. **Status updated**: The task status returns to `completed` (or `error`) when done

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl --location 'https://cloud.blackbox.ai/api/tasks/YOUR_TASK_ID/continue' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "currentPrompt": "Also add unit tests for the new payment module"
  }'
  ```

  ```bash cURL - Override Agent theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl --location 'https://cloud.blackbox.ai/api/tasks/YOUR_TASK_ID/continue' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "currentPrompt": "Refactor the authentication logic to use middleware",
      "selectedAgent": "claude",
      "selectedModel": "blackboxai/anthropic/claude-sonnet-4.5"
  }'
  ```

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

  const response = await fetch(API_URL, {
      method: "POST",
      headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          currentPrompt: "Also add unit tests for the new payment module",
      }),
  });

  const result = await response.json();
  console.log(result);

  // Poll for completion
  const checkStatus = async () => {
      const statusResponse = await fetch(
          `https://cloud.blackbox.ai/api/tasks/${TASK_ID}`,
          { headers: { Authorization: `Bearer ${API_KEY}` } }
      );
      const { task } = await statusResponse.json();

      const lastFollowup = task.followupMessages?.at(-1);
      console.log("Follow-up status:", lastFollowup?.status);

      if (lastFollowup?.status === "completed" || lastFollowup?.status === "error") {
          console.log("Follow-up finished:", lastFollowup.status);
      } else {
          setTimeout(checkStatus, 5000);
      }
  };

  checkStatus();
  ```

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

  API_KEY = "YOUR_API_KEY"
  TASK_ID = "YOUR_TASK_ID"
  CONTINUE_URL = f"https://cloud.blackbox.ai/api/tasks/{TASK_ID}/continue"
  STATUS_URL = f"https://cloud.blackbox.ai/api/tasks/{TASK_ID}"

  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {API_KEY}"
  }

  # Send follow-up
  response = requests.post(CONTINUE_URL, headers=headers, json={
      "currentPrompt": "Also add unit tests for the new payment module"
  })
  print("Continue response:", response.json())

  # Poll for completion
  def check_status():
      r = requests.get(STATUS_URL, headers=headers)
      task = r.json()["task"]
      followups = task.get("followupMessages") or []

      if followups:
          last = followups[-1]
          print(f"Follow-up status: {last['status']}")
          if last["status"] in ("completed", "error"):
              print(f"✓ Follow-up finished with status: {last['status']}")
              return True
      return False

  while not check_status():
      time.sleep(5)
  ```

  ```python Python - Multi-Agent Follow-up theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests
  import time

  API_KEY = "YOUR_API_KEY"
  TASK_ID = "YOUR_TASK_ID"
  CONTINUE_URL = f"https://cloud.blackbox.ai/api/tasks/{TASK_ID}/continue"

  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {API_KEY}"
  }

  # Send multi-agent follow-up
  response = requests.post(CONTINUE_URL, headers=headers, json={
      "currentPrompt": "Add comprehensive error handling and logging",
      "multiLaunch": True,
      "selectedAgents": [
          {
              "agent": "claude",
              "model": "blackboxai/anthropic/claude-sonnet-4.5"
          },
          {
              "agent": "blackbox",
              "model": "blackboxai/blackbox-pro"
          }
      ]
  })

  result = response.json()
  print("Multi-agent follow-up started:", result)
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "success": true,
    "message": "Task continue started successfully"
  }
  ```

  ```json Error - Task Not Found theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Task not found"
  }
  ```

  ```json Error - Unauthorized theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Unauthorized"
  }
  ```

  ```json Error - Insufficient Credits theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Insufficient credits. Please add credits or switch to a free model.",
    "code": "INSUFFICIENT_CREDITS"
  }
  ```

  ```json Error - Missing Prompt theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Current prompt is required"
  }
  ```
</ResponseExample>

## Polling for Follow-up Completion

After calling continue, the task's `followupMessages` array is updated with the new follow-up entry. Poll [Get Task](/api-reference/get-task) and inspect the **last element** of `followupMessages`:

```json Follow-up Message Structure theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "message": "Also add unit tests for the new payment module",
  "timestamp": "2025-11-21T10:35:00.000Z",
  "selectedAgent": "blackbox",
  "selectedModel": "blackboxai/blackbox-pro",
  "status": "completed",
  "statusMessage": null
}
```

| `status` value | Meaning                                           |
| -------------- | ------------------------------------------------- |
| `processing`   | Agent is actively working on the follow-up        |
| `completed`    | Follow-up finished successfully                   |
| `error`        | Follow-up failed; see `statusMessage` for details |

## Error Codes

| Status Code | Error                 | Description                                                  |
| ----------- | --------------------- | ------------------------------------------------------------ |
| 200         | Success               | Follow-up started successfully                               |
| 400         | Bad Request           | Missing `currentPrompt` or invalid multi-agent configuration |
| 401         | Unauthorized          | Invalid or missing API key                                   |
| 402         | Payment Required      | Insufficient credits for the selected model                  |
| 404         | Not Found             | Task not found or access denied                              |
| 500         | Internal Server Error | File upload or sandbox creation failed                       |

## Related Endpoints

* [Create an Agent Task](/api-reference/task) — Start a new single-agent task
* [Create a Multi-Agent Task](/api-reference/multi-agent-task) — Start a new multi-agent task
* [Get Task](/api-reference/get-task) — Retrieve task details and follow-up statuses
* [Stream Logs](/api-reference/stream-logs) — Stream real-time execution logs
* [Cancel Task](/api-reference/cancel-task) — Stop a running task