> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouncedetector.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Batch

> Cancel a pending or processing batch.

Cancel a pending or processing batch. Completed or already cancelled batches cannot be cancelled.

## Request

<ParamField path="id" type="string" required>
  Batch ID to cancel
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message
</ResponseField>

<ResponseField name="batch" type="object">
  Updated batch with status `cancelled`
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl -X POST "https://api.bouncedetector.com/api/v1/batches/507f1f77bcf86cd799439011/cancel" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "Batch cancelled",
    "batch": {
      "_id": "507f1f77bcf86cd799439011",
      "status": "cancelled",
      "totalCount": 100,
      "processedCount": 45,
      "createdAt": "2025-03-09T14:25:00.000Z"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /api/v1/batches/{id}/cancel
openapi: 3.1.0
info:
  title: BounceDetector API
  description: >-
    Email verification API. All endpoints require API key authentication via
    Bearer token.
  version: 1.0.0
servers:
  - url: https://api.bouncedetector.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Verification
    description: Single and bulk email verification
  - name: Batch
    description: Batch job management
paths:
  /api/v1/batches/{id}/cancel:
    post:
      tags:
        - Batch
      summary: Cancel batch
      description: >-
        Cancel a pending or processing batch. Completed or already cancelled
        batches cannot be cancelled.
      operationId: cancelBatch
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  batch:
                    $ref: '#/components/schemas/Batch'
        '400':
          description: Batch cannot be cancelled
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Batch not found
components:
  schemas:
    Batch:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - cancelled
        totalCount:
          type: integer
        processedCount:
          type: integer
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Your API key (e.g. bdt_abc123...). Obtain from the dashboard.

````