> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel a Message Batch

> Cancel a Message Batch through the OMA API.

<Info>Use `?beta=true` with `anthropic-beta: message-batches-2024-09-24` for the beta request and response shapes shown here.</Info>


## OpenAPI

````yaml /openapi/oma.en.json post /v1/messages/batches/{message_batch_id}/cancel
openapi: 3.1.0
info:
  title: OMA API Reference
  version: 1.0.0
  description: Open Managed Agents application API reference.
servers:
  - url: http://localhost:38080
    description: Local OMA server
security:
  - omaApiKey: []
  - omaBearer: []
paths:
  /v1/messages/batches/{message_batch_id}/cancel:
    post:
      summary: Cancel a Message Batch
      description: >-
        Batches may be canceled any time before processing ends. Once
        cancellation is initiated, the batch enters a `canceling` state, at
        which time the system may complete any in-progress, non-interruptible
        requests before finalizing cancellation.


        The number of canceled requests is specified in `request_counts`. To
        determine which requests were canceled, check the individual results
        within the batch. Note that cancellation may not result in any canceled
        requests if they were non-interruptible.


        Learn more about the Message Batches API in our user guide
      operationId: beta_message_batches_cancel
      parameters:
        - name: beta
          in: query
          required: true
          description: Selects the beta API contract for this endpoint. Must be `true`.
          schema:
            type: boolean
            enum:
              - true
        - name: message_batch_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the Message Batch.
            title: Message Batch Id
          description: ID of the Message Batch.
        - name: anthropic-beta
          in: header
          required: true
          schema:
            type: string
            items:
              type: string
            description: >-
              Optional header to specify the beta version(s) you want to use.


              To use multiple betas, use a comma separated list like
              `beta1,beta2` or specify the header multiple times for each beta.
            title: Anthropic-Beta
            x-stainless-override-schema:
              x-stainless-param: betas
              x-stainless-extend-default: true
              type: array
              description: Optional header to specify the beta version(s) you want to use.
              items:
                $ref: '#/components/schemas/AnthropicBeta'
            x-default: message-batches-2024-09-24
          description: >-
            Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2`
            or specify the header multiple times for each beta.
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
            description: |-
              The version of the OMA API you want to use.

              Read more about versioning and our version history here.
            title: Anthropic-Version
          description: |-
            The version of the OMA API you want to use.

            Read more about versioning and our version history here.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaMessageBatch'
        4XX:
          description: |-
            Error response.

            See our errors documentation for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
components:
  schemas:
    BetaMessageBatch:
      properties:
        archived_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Archived At
          description: >-
            RFC 3339 datetime string representing the time at which the Message
            Batch was archived and its results became unavailable.
          examples:
            - '2024-08-20T18:37:24.100435Z'
        cancel_initiated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cancel Initiated At
          description: >-
            RFC 3339 datetime string representing the time at which cancellation
            was initiated for the Message Batch. Specified only if cancellation
            was initiated.
          examples:
            - '2024-08-20T18:37:24.100435Z'
        created_at:
          type: string
          format: date-time
          title: Created At
          description: >-
            RFC 3339 datetime string representing the time at which the Message
            Batch was created.
          examples:
            - '2024-08-20T18:37:24.100435Z'
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
          description: >-
            RFC 3339 datetime string representing the time at which processing
            for the Message Batch ended. Specified only once processing ends.


            Processing ends when every request in a Message Batch has either
            succeeded, errored, canceled, or expired.
          examples:
            - '2024-08-20T18:37:24.100435Z'
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: >-
            RFC 3339 datetime string representing the time at which the Message
            Batch will expire and end processing, which is 24 hours after
            creation.
          examples:
            - '2024-08-20T18:37:24.100435Z'
        id:
          type: string
          title: Id
          description: |-
            Unique object identifier.

            The format and length of IDs may change over time.
          examples:
            - msgbatch_013Zva2CMHLNnXjNJJKqJ2EF
        processing_status:
          type: string
          enum:
            - in_progress
            - canceling
            - ended
          title: Processing Status
          description: Processing status of the Message Batch.
          examples:
            - in_progress
        request_counts:
          $ref: '#/components/schemas/BetaRequestCounts'
          description: >-
            Tallies requests within the Message Batch, categorized by their
            status.


            Requests start as `processing` and move to one of the other statuses
            only once processing of the entire batch ends. The sum of all values
            always matches the total number of requests in the batch.
        results_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Results Url
          description: >-
            URL to a `.jsonl` file containing the results of the Message Batch
            requests. Specified only once processing ends.


            Results in the file are not guaranteed to be in the same order as
            requests. Use the `custom_id` field to match results to requests.
          examples:
            - >-
              https://oma.example.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results
        type:
          type: string
          const: message_batch
          title: Type
          description: |-
            Object type.

            For Message Batches, this is always `"message_batch"`.
          default: message_batch
      type: object
      required:
        - archived_at
        - cancel_initiated_at
        - created_at
        - ended_at
        - expires_at
        - id
        - processing_status
        - request_counts
        - results_url
        - type
      title: MessageBatch
    BetaErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error:
                $ref: '#/components/schemas/BetaAPIError'
              authentication_error:
                $ref: '#/components/schemas/BetaAuthenticationError'
              billing_error:
                $ref: '#/components/schemas/BetaBillingError'
              invalid_request_error:
                $ref: '#/components/schemas/BetaInvalidRequestError'
              not_found_error:
                $ref: '#/components/schemas/BetaNotFoundError'
              overloaded_error:
                $ref: '#/components/schemas/BetaOverloadedError'
              permission_error:
                $ref: '#/components/schemas/BetaPermissionError'
              rate_limit_error:
                $ref: '#/components/schemas/BetaRateLimitError'
              timeout_error:
                $ref: '#/components/schemas/BetaGatewayTimeoutError'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/BetaInvalidRequestError'
            - $ref: '#/components/schemas/BetaAuthenticationError'
            - $ref: '#/components/schemas/BetaBillingError'
            - $ref: '#/components/schemas/BetaPermissionError'
            - $ref: '#/components/schemas/BetaNotFoundError'
            - $ref: '#/components/schemas/BetaRateLimitError'
            - $ref: '#/components/schemas/BetaGatewayTimeoutError'
            - $ref: '#/components/schemas/BetaAPIError'
            - $ref: '#/components/schemas/BetaOverloadedError'
          title: Error
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        type:
          const: error
          default: error
          title: Type
          type: string
      required:
        - error
        - request_id
        - type
      title: ErrorResponse
      type: object
    BetaRequestCounts:
      properties:
        canceled:
          type: integer
          title: Canceled
          description: |-
            Number of requests in the Message Batch that have been canceled.

            This is zero until processing of the entire Message Batch has ended.
          default: 0
          examples:
            - 10
        errored:
          type: integer
          title: Errored
          description: |-
            Number of requests in the Message Batch that encountered an error.

            This is zero until processing of the entire Message Batch has ended.
          default: 0
          examples:
            - 30
        expired:
          type: integer
          title: Expired
          description: |-
            Number of requests in the Message Batch that have expired.

            This is zero until processing of the entire Message Batch has ended.
          default: 0
          examples:
            - 10
        processing:
          type: integer
          title: Processing
          description: Number of requests in the Message Batch that are processing.
          default: 0
          examples:
            - 100
        succeeded:
          type: integer
          title: Succeeded
          description: >-
            Number of requests in the Message Batch that have completed
            successfully.


            This is zero until processing of the entire Message Batch has ended.
          default: 0
          examples:
            - 50
      type: object
      required:
        - canceled
        - errored
        - expired
        - processing
        - succeeded
      title: RequestCounts
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
        - message
        - type
      title: APIError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
        - message
        - type
      title: AuthenticationError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
        - message
        - type
      title: BillingError
      type: object
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
        - message
        - type
      title: InvalidRequestError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
        - message
        - type
      title: NotFoundError
      type: object
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
        - message
        - type
      title: OverloadedError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
        - message
        - type
      title: PermissionError
      type: object
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: Message
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: Type
          type: string
      required:
        - message
        - type
      title: RateLimitError
      type: object
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
        - message
        - type
      title: GatewayTimeoutError
      type: object
  securitySchemes:
    omaApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: OMA workspace API key.
      x-default: sk-ant-local-default
    omaBearer:
      type: http
      scheme: bearer
      description: OMA workspace API key sent as a bearer token.

````