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

> Cancel a queued item or all queued items of a batch.



## OpenAPI

````yaml openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/cancel
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/cancel:
    post:
      summary: Cancel an item or a batch
      description: >-
        Move queued items to `cancelled`. An item a worker has already taken
        runs to completion, so cancelling does not stop work in flight.
      operationId: batch_cancel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCancelRequest'
      responses:
        '200':
          description: The queued items are cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCancelResponse'
        '400':
          description: >-
            The body is malformed, it does not identify exactly one item or
            batch, or the item has already started or completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
        '403':
          description: The item or batch belongs to another caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
        '404':
          description: No item or batch with this id belongs to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
        '409':
          description: >-
            There is nothing left to cancel: the item already started, or every
            item of the batch is in a terminal state.
          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 or batch could not be cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchError'
components:
  schemas:
    BatchCancelRequest:
      title: BatchCancelRequest
      type: object
      description: Provide exactly one of `task_id` or `batch_id`.
      properties:
        task_id:
          type: string
          description: Cancel this one item.
        batch_id:
          type: string
          description: Cancel every queued item of this batch.
    BatchCancelResponse:
      title: BatchCancelResponse
      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:
            message:
              type: string
            task_id:
              type: string
              description: Echoed when the request named one item.
            batch_id:
              type: string
              description: Echoed when the request named a batch.
            cancelled_items:
              type: integer
              description: >-
                How many items moved to `cancelled`. Only a queued item can be
                cancelled, so an item already running is not counted and runs to
                completion.
        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

````