> ## Documentation Index > Fetch the complete documentation index at: https://docs.biohub.ai/llms.txt > Use this file to discover all available pages before exploring further. # batch_list > Read batch status counts and optionally page through its item records. ## OpenAPI ````yaml openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/list openapi: 3.1.0 info: title: Biohub Platform Batch API version: 1.0.0 servers: - url: https://biohub.ai security: - HTTPBearer: [] paths: /api/v1/batch/list: post: summary: Count and page a batch's items description: >- Return a batch's per-status counts, and optionally a page of its items. Poll this rather than /batch/status when you want to know how far a batch has got. operationId: batch_list requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchListRequest' responses: '200': description: The batch's counts, and a page of items when asked for. content: application/json: schema: $ref: '#/components/schemas/BatchListResponse' '400': description: >- The body is malformed, `limit` is out of range, or `cursor` is not a cursor this route issued. content: application/json: schema: $ref: '#/components/schemas/BatchError' '404': description: No batch with this id belongs to the caller. content: application/json: schema: $ref: '#/components/schemas/BatchError' '429': description: A rate limit refused the call. content: application/json: schema: $ref: '#/components/schemas/BatchError' '500': description: The batch could not be read. content: application/json: schema: $ref: '#/components/schemas/BatchError' '502': description: The batch's status could not be retrieved. content: application/json: schema: $ref: '#/components/schemas/BatchError' components: schemas: BatchListRequest: title: BatchListRequest type: object required: - batch_id properties: batch_id: type: string description: The batch to read, from the submit response. status: type: array minItems: 1 items: type: string enum: - queued - in_progress - cancelled - done - failed description: >- Filter returned items to these statuses. Counts and total remain batch-wide. include_responses: type: boolean default: false description: >- Return the `items` array as well as the counts. Left off, the call reads counts only, which is what a poll should do. limit: type: integer minimum: 1 maximum: 1000 default: 100 description: Items per page. Applies only with `include_responses`. cursor: type: - string - 'null' description: The `cursor` the previous page returned. BatchListResponse: title: BatchListResponse type: object description: >- Every Batch API route answers with this envelope. A failure carries `message` instead of `data`. properties: status: type: string const: success data: type: object properties: batch_id: type: string endpoint: type: string description: The submitted inference endpoint. status: type: string enum: - in_progress - done - cancelled - failed description: >- The batch itself, not one item. Derived on every read rather than stored. Explicit cancellation or dispatch failure takes precedence; otherwise it is `done` once all items have been submitted and accounted for, and none is queued or running. Individual items may have failed even when the batch is `done`. counts: type: object additionalProperties: type: integer description: >- How many items hold each status. A status no item holds is absent rather than zero, so read it with a default. total: type: integer description: How many items the batch holds. expires_at: type: string format: date-time description: >- When items still queued are cancelled: 24 hours after the batch was submitted. An item a worker has already started runs to completion. A cancelled item is never charged. results_expire_at: type: string format: date-time description: >- When results stop being served: 31 days after the batch was submitted. Download what you need before then. After it, items keep their `status` but carry no `response`, `response_available` or `error`. items: type: array items: $ref: '#/components/schemas/BatchListItem' description: Present only when the request set `include_responses`. cursor: type: - string - 'null' description: >- Present with `include_responses`. Pass a non-null cursor to read the next page. Null after a short page; a full final page can require one more read returning no items. request_id: type: string BatchError: title: BatchError type: object description: >- Every Batch API route answers with this envelope. A failure carries `message` instead of `data`. properties: status: type: string const: error message: type: string description: What is wrong with the request, and how to correct it. request_id: type: string description: Quote this when you report a problem with the call. results_expire_at: type: string format: date-time description: >- Present on a 410 from /batch/status: when the item's results expired. BatchListItem: title: BatchListItem type: object description: One item of a batch, as /batch/list reports it. properties: task_id: type: string status: type: string enum: - queued - in_progress - cancelled - done - failed response: type: - object - string description: >- The endpoint's inline result, when available. Externally stored results are reported by `response_available` instead; read /batch/status for the download URL and any artifact URLs. response_available: type: boolean description: The item produced a response. Read it from /batch/status. error: type: - object - string description: Why the item failed, or why the queue limit cancelled it. securitySchemes: HTTPBearer: type: http scheme: bearer ````