Batch Status API: Query Multiple Task Results

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.

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.

Endpoint

GET https://api.apixo.ai/api/v1/generateTask/{model}/batches/{batchId}

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

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

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

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 to receive a terminal notification for every accepted batch item.

​Endpoint

​States

​Completed batch with successful items

​Batch Status response fields

​A completed batch with both success and failure

​Query one batch item by task ID

​When a webhook is missing

​Common errors

​Next step

Endpoint

States

Completed batch with successful items

Batch Status response fields

A completed batch with both success and failure

Query one batch item by task ID

When a webhook is missing

Common errors

Next step