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

> Read one batch item's status, result, and artifact URLs.



## OpenAPI

````yaml openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/status
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/status:
    post:
      summary: Read one item and its result
      description: >-
        Return one item's status, its response once it is `done`, and presigned
        URLs for any artifact it wrote.
      operationId: batch_status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchStatusRequest'
      responses:
        '200':
          description: The item's status, and its result when it has one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
        '400':
          description: The body is not valid JSON, or a field is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
        '404':
          description: >-
            No item with this id belongs to the caller. Another caller's item
            also reads as 404, not 403. Passing a batch id here returns the id
            of its first item, so read the correction and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
        '410':
          description: >-
            The item's results expired 31 days after submission and are no
            longer available. The body's `results_expire_at` gives when.
          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 item's status or result could not be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
        '502':
          description: The item's status or result could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
components:
  schemas:
    BatchStatusRequest:
      title: BatchStatusRequest
      type: object
      required:
        - task_id
      properties:
        task_id:
          type: string
          description: The item to read. One item per call.
    BatchStatusResponse:
      title: BatchStatusResponse
      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:
            status:
              type: string
              enum:
                - queued
                - in_progress
                - cancelled
                - done
                - failed
              description: >-
                `queued` until a worker takes the item, then `in_progress`, then
                one of `done`, `failed` or `cancelled`. A terminal status does
                not change again. An item still `queued` at `expires_at` becomes
                `cancelled`.
            response:
              type:
                - object
                - string
              description: >-
                The endpoint's result, returned inline as an object or string,
                or as a signed download URL when stored externally. The endpoint
                determines the result's contents. Download signed URLs without
                the Biohub bearer token; read status again to refresh an expired
                URL.
            error:
              type:
                - object
                - string
              description: >-
                Why the item failed, or why the queue limit cancelled it.
                Present when `status` is `failed`, and when `status` is
                `cancelled` because the item was still queued at `expires_at`.
                Absent on an item you cancelled.
            artifacts:
              type: object
              additionalProperties:
                type: string
              description: >-
                Signed download URLs for additional outputs, keyed by artifact
                name. Download without the Biohub bearer token. Read status
                again to refresh expired URLs.
            artifacts_expire_in:
              type: integer
              description: >-
                Seconds until the artifact URLs stop working. Each URL is signed
                per read; this reports the shortest lifetime in this response,
                so the value holds for all of them.
            tokens_used:
              type: integer
            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, this
                route returns 410.
        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.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````