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

# Cancel a Batch

> Stop a running or pending batch and refund credits for unprocessed items

## Overview

Cancels a batch that is currently `pending` or `running`. Credits reserved for items that have **not yet started** are refunded automatically. Items already being processed will complete normally.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.spidra.io/api/batch/scrape/YOUR_BATCH_ID \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `https://api.spidra.io/api/batch/scrape/${batchId}`,
    {
      method: "DELETE",
      headers: { "x-api-key": "YOUR_API_KEY" },
    }
  );
  const { cancelledItems, creditsRefunded } = await res.json();
  console.log(`Cancelled ${cancelledItems} items, refunded ${creditsRefunded} credits`);
  ```

  ```python Python theme={null}
  import requests

  resp = requests.delete(
      f"https://api.spidra.io/api/batch/scrape/{batch_id}",
      headers={"x-api-key": "YOUR_API_KEY"},
  )
  data = resp.json()
  print(f"Cancelled {data['cancelledItems']} items, refunded {data['creditsRefunded']} credits")
  ```
</CodeGroup>

***

## Response

```json theme={null}
{
  "status": "cancelled",
  "cancelledItems": 8,
  "creditsRefunded": 16
}
```

| Field             | Type          | Description                                                                               |
| ----------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `status`          | `"cancelled"` | Confirms the batch was cancelled                                                          |
| `cancelledItems`  | `number`      | Number of pending items that were stopped. Items already running are not counted          |
| `creditsRefunded` | `number`      | Credits returned to your balance. Calculated as `cancelledItems × reservedCreditsPerItem` |

<Note>
  Items that were already `running` when you cancelled will finish processing and consume their credits. Only `pending` items are cancelled and refunded.
</Note>

***

## Errors

| Code  | Reason                                                                                                   |
| ----- | -------------------------------------------------------------------------------------------------------- |
| `401` | Missing `x-api-key` header                                                                               |
| `403` | Invalid or expired API key                                                                               |
| `404` | No batch found with this ID, or it belongs to a different user                                           |
| `409` | The batch is already in a terminal state (`completed`, `failed`, or `cancelled`) and cannot be cancelled |

**Already terminal:**

```json theme={null}
{
  "status": "error",
  "message": "Cannot cancel a batch that is already completed.",
  "code": "ALREADY_TERMINAL"
}
```

***

<CardGroup cols={2}>
  <Card title="Retry Failed Batch Scrapes" icon="rotate" href="/api-reference/scraping/batch-scrape-retry">
    Re-queue failed items instead of cancelling
  </Card>

  <Card title="Get Batch Status" icon="magnifying-glass" href="/api-reference/scraping/batch-scrape-status">
    Check current status before cancelling
  </Card>
</CardGroup>


## OpenAPI

````yaml DELETE /batch/scrape/{batchId}
openapi: 3.1.0
info:
  title: Spidra API
  version: 1.0.0
  description: >-
    Public API endpoints for web scraping via Spidra. Authentication is via API
    key passed in the `x-api-key` header.
servers:
  - url: https://api.spidra.io/api
security:
  - ApiKeyAuth: []
paths:
  /batch/scrape/{batchId}:
    delete:
      tags:
        - Batch Scraping
      summary: Cancel a Batch
      description: >-
        Cancel a pending or running batch. Refunds credits for items that have
        not started yet. Items already running complete normally.
      parameters:
        - name: batchId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The batch ID to cancel
      responses:
        '200':
          description: Batch cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - cancelled
                  cancelledItems:
                    type: integer
                    description: Number of pending items that were stopped
                  creditsRefunded:
                    type: integer
                    description: Credits returned to your balance
              example:
                status: cancelled
                cancelledItems: 8
                creditsRefunded: 16
        '401':
          description: Missing x-api-key header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch not found or belongs to a different user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Batch is already in a terminal state and cannot be cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: Cannot cancel a batch that is already completed.
                code: ALREADY_TERMINAL
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
      required:
        - status
        - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````