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

# Cancel a batch (deprecated)

> **Deprecated — use `POST /batches/{batch_id}/cancel` instead.** This verb performs exactly the same cancellation and is kept only for existing integrations; it additionally requires an admin role, which the POST verb does not.

Stop a batch. Any batch that has not already finished can be cancelled — including one that is actively running.

What happens: further sends stop before this call returns — nothing still waiting in the queue is handed to the provider after that point — the batch's workflow is cancelled, and the batch's status becomes `cancelled`. Every record that had not yet been sent is then settled as `unprocessed` so nothing is left in limbo. On a large batch that settling lands a few seconds after the response rather than inside it: a million-row batch is millions of record updates, and holding the request open for them would time out at the load balancer. Read the counters a moment later.

What does NOT happen: records already handed to the provider are not recalled. Their outcomes are still collected and written back, so the batch's final counts tell you exactly what reached the provider before the cancel — cancel stops all future sends, it does not rewrite the past.

Cancelling is a normal part of running a batch and needs no special role: any key for the owning organization can cancel that organization's own batches. A batch that has already completed, failed or been cancelled returns 409. Cross-tenant access returns 404, never 403.



## OpenAPI

````yaml /openapi.json delete /flows/batches/{batch_id}
openapi: 3.1.0
info:
  title: GetDialed API
  version: 0.1.0
servers:
  - url: https://api.getdialed.ai/v1
    description: Production
security: []
paths:
  /flows/batches/{batch_id}:
    delete:
      tags:
        - batches
      summary: Cancel a batch (deprecated)
      description: >-
        **Deprecated — use `POST /batches/{batch_id}/cancel` instead.** This
        verb performs exactly the same cancellation and is kept only for
        existing integrations; it additionally requires an admin role, which the
        POST verb does not.


        Stop a batch. Any batch that has not already finished can be cancelled —
        including one that is actively running.


        What happens: further sends stop before this call returns — nothing
        still waiting in the queue is handed to the provider after that point —
        the batch's workflow is cancelled, and the batch's status becomes
        `cancelled`. Every record that had not yet been sent is then settled as
        `unprocessed` so nothing is left in limbo. On a large batch that
        settling lands a few seconds after the response rather than inside it: a
        million-row batch is millions of record updates, and holding the request
        open for them would time out at the load balancer. Read the counters a
        moment later.


        What does NOT happen: records already handed to the provider are not
        recalled. Their outcomes are still collected and written back, so the
        batch's final counts tell you exactly what reached the provider before
        the cancel — cancel stops all future sends, it does not rewrite the
        past.


        Cancelling is a normal part of running a batch and needs no special
        role: any key for the owning organization can cancel that organization's
        own batches. A batch that has already completed, failed or been
        cancelled returns 409. Cross-tenant access returns 404, never 403.
      operationId: cancel_batch_flows_batches__batch_id__delete
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            title: Batch Id
      responses:
        '204':
          description: Successful Response
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              example:
                detail: Authentication required
        '403':
          description: Caller is authenticated but not an admin
          content:
            application/json:
              example:
                detail: Admin role required
        '404':
          description: >-
            No such batch for this organization (cross-tenant access also
            returns 404)
          content:
            application/json:
              example:
                detail: Batch not found
        '409':
          description: The batch has already finished (completed, failed, or cancelled)
          content:
            application/json:
              example:
                detail: >-
                  Cannot cancel a batch that has already finished — a terminal
                  batch has nothing left to stop.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded — retry after the Retry-After header
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              example:
                detail: 'Rate limit exceeded: 100 per 1 minute'
      deprecated: true
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````