> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Status API: Query Multiple Task Results

> Query a batch's overall progress, every item state, and terminal results for accepted batch generation tasks.

Use Batch Status to see whether a whole batch has completed and which items succeeded, failed, or were rejected. Submit the batch first with [Batch Generate](/docs/api-reference/batch-generate).

<Info>
  Every accepted batch item has `items[].taskId`. You can also query that one task at any time through Single Tasks > Status Task: `GET /api/v1/statusTask/{model}?taskId={taskId}`. Batch Status is best for whole-batch progress; Status Task is best for diagnosing one task.
</Info>

## Endpoint

```http theme={null}
GET https://api.apixo.ai/api/v1/generateTask/{model}/batches/{batchId}
```

```bash theme={null}
curl "https://api.apixo.ai/api/v1/generateTask/seedream-4-5/batches/batch_123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## States

| State | Appears on | Meaning |
| - | - | - |
| `queued` | Batch or item | Accepted and waiting for execution. |
| `running` | Batch or item | At least one task is executing. |
| `succeeded` | Item | The task completed successfully. |
| `failed` | Item | The task reached a failed terminal state. |
| `rejected` | Item | The item was not accepted at submission time. |
| `completed` | Batch | Every item has reached a terminal state. |
| `completed_with_errors` | Batch | No item in the batch was successfully accepted. |

## Completed batch with successful items

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_123",
    "model": "seedream-4-5",
    "status": "completed",
    "replayed": false,
    "newlyAcceptedCount": 2,
    "reusedCount": 0,
    "rejectedCount": 0,
    "items": [
      {
        "ordinal": 0,
        "clientItemId": "order-1001",
        "taskId": "task_123",
        "accepted": true,
        "status": "succeeded",
        "result": {
          "taskId": "task_123",
          "state": "success",
          "resultJson": "{\"resultUrls\":[\"https://cdn.example.com/output-1.jpg\"]}"
        }
      },
      {
        "ordinal": 1,
        "clientItemId": "order-1002",
        "taskId": "task_456",
        "accepted": true,
        "status": "succeeded",
        "result": {
          "taskId": "task_456",
          "state": "success",
          "resultJson": "{\"resultUrls\":[\"https://cdn.example.com/output-2.jpg\"]}"
        }
      }
    ]
  }
}
```

### Batch Status response fields

| Field | Type | Description |
| - | - | - |
| `code` | integer | Query result code. `200` means the status query succeeded; it does not mean every generation task succeeded. |
| `message` | string | API result message. `success` is returned for a successful lookup. |
| `data.batchId` | string | ID of the queried batch. |
| `data.model` | string | Public model ID used to submit this batch. |
| `data.status` | string | Overall batch state. `completed` means every item is terminal. |
| `data.replayed` | boolean | Whether the view is from a submission idempotency replay. Direct status queries normally return `false`. |
| `data.newlyAcceptedCount` | integer | Number of newly accepted items in the batch. |
| `data.reusedCount` | integer | Number of items that reused an existing task. |
| `data.rejectedCount` | integer | Number of items rejected during submission. |
| `data.items` | array | Current state and terminal result of every item. |
| `data.items[].ordinal` | integer | Zero-based item position in the original request. |
| `data.items[].clientItemId` | string | Caller-provided business locator. Use it to associate a result with your order or job. |
| `data.items[].taskId` | string \| null | Accepted task ID. It can also be used with the single-task Status Task endpoint; it is `null` for rejected items. |
| `data.items[].accepted` | boolean | Whether the item was accepted for execution. |
| `data.items[].status` | string | Item state: `queued`, `running`, `succeeded`, `failed`, or `rejected`. |
| `data.items[].error` | object | Present only for rejected items; contains the submission error code and message. |
| `data.items[].result` | object | Present only for terminal items; the public terminal result of the underlying task. |
| `data.items[].result.taskId` | string | Task ID for the terminal item. |
| `data.items[].result.state` | string | Underlying terminal state, such as `success` or `failed`. |
| `data.items[].result.resultJson` | string | Usually present for a successful task. It is a JSON string containing public model output, such as `resultUrls`. |
| `data.items[].result.failCode` | string | Usually present for a failed task. Programmatic failure code. |
| `data.items[].result.failMsg` | string | Usually present for a failed task. Developer-facing failure explanation. |

For `succeeded` items, parse `items[].result.resultJson` to read result URLs or other public model output.

## A completed batch with both success and failure

HTTP `200` means the lookup succeeded. Determine generation success from each item's `status` and `result.state`.

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_124",
    "status": "completed",
    "items": [
      {
        "ordinal": 0,
        "clientItemId": "order-1003",
        "taskId": "task_789",
        "accepted": true,
        "status": "succeeded",
        "result": {
          "taskId": "task_789",
          "state": "success",
          "resultJson": "{\"resultUrls\":[\"https://cdn.example.com/output-3.jpg\"]}"
        }
      },
      {
        "ordinal": 1,
        "clientItemId": "order-1004",
        "taskId": "task_987",
        "accepted": true,
        "status": "failed",
        "result": {
          "taskId": "task_987",
          "state": "failed",
          "failCode": "CONTENT_VIOLATION",
          "failMsg": "Content violates usage policy"
        }
      }
    ]
  }
}
```

Associate results with your business records through `clientItemId`. Save successful output, and record `failCode` and `failMsg` for failed items. To create new work after a failure, use a new business operation and a new `idempotency_key`.

## Query one batch item by task ID

For example, after Batch Status returns `taskId: "task_987"`, you can independently inspect that failed task:

```bash theme={null}
curl "https://api.apixo.ai/api/v1/statusTask/seedream-4-5?taskId=task_987" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See Single Tasks > Status Task for that response format and states. An individual lookup does not alter the batch, resubmit work, or trigger re-execution.

## When a webhook is missing

Webhooks are terminal notifications, not the only record of task state. Use Batch Status when your receiver was unavailable, while a retry is pending, after retries are exhausted, or during reconciliation.

Start with `batchId` to see the entire batch, then use an individual `taskId` with Single Tasks > Status Task when one item needs deeper investigation.

## Common errors

| Situation | What to do |
| - | - |
| `batchId` does not exist or belongs to another account | Verify that the API key and stored `batchId` belong to the same account. |
| `{model}` does not match the submission model | Use the same public model ID used when submitting the batch. |
| The batch is `queued` or `running` | Query again later or wait for a webhook. |
| An item is `failed` | Inspect its `result` failure fields, then use `taskId` with Status Task if needed. |

## Next step

Read [Batch Webhooks](/docs/api-reference/batch-webhooks) to receive a terminal notification for every accepted batch item.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.