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

# List Batch Jobs

> Retrieve a paginated list of all your batch scrape jobs

Returns a paginated list of all batch jobs for your account, ordered by most recent first. Item-level results are not included. Use `GET /api/batch/scrape/{batchId}` to fetch those for a specific batch.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.spidra.io/api/batch/scrape?page=1&limit=20" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://api.spidra.io/api/batch/scrape?page=1&limit=20",
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  const { jobs, pagination } = await res.json();
  ```

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

  resp = requests.get(
      "https://api.spidra.io/api/batch/scrape",
      headers={"x-api-key": "YOUR_API_KEY"},
      params={"page": 1, "limit": 20},
  )
  data = resp.json()
  jobs = data["jobs"]
  pagination = data["pagination"]
  ```
</CodeGroup>

***

## Query Parameters

| Parameter | Type     | Default | Description                 |
| --------- | -------- | ------- | --------------------------- |
| `page`    | `number` | `1`     | Page number (1-based)       |
| `limit`   | `number` | `20`    | Jobs per page. Maximum `50` |

***

## Response

```json theme={null}
{
  "jobs": [
    {
      "uuid": "f3a2b1c0-0000-0000-0000-000000000000",
      "status": "completed",
      "totalUrls": 10,
      "completedCount": 9,
      "failedCount": 1,
      "outputFormat": "json",
      "scrapingChannel": "api",
      "createdAt": "2024-01-15T10:00:00Z",
      "finishedAt": "2024-01-15T10:01:30Z"
    },
    {
      "uuid": "e2c1a0b9-0000-0000-0000-000000000000",
      "status": "running",
      "totalUrls": 25,
      "completedCount": 12,
      "failedCount": 0,
      "outputFormat": "json",
      "scrapingChannel": "api",
      "createdAt": "2024-01-15T10:05:00Z",
      "finishedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3
  }
}
```

### Job Entry Fields

| Field             | Type               | Description                                                   |
| ----------------- | ------------------ | ------------------------------------------------------------- |
| `uuid`            | `string`           | Batch ID — use this with other endpoints                      |
| `status`          | `string`           | `pending`, `running`, `completed`, `failed`, or `cancelled`   |
| `totalUrls`       | `number`           | How many URLs were in this batch                              |
| `completedCount`  | `number`           | Items that completed successfully                             |
| `failedCount`     | `number`           | Items that failed                                             |
| `outputFormat`    | `string`           | `"json"` or `"markdown"`                                      |
| `scrapingChannel` | `string`           | `"api"` or `"playground"`                                     |
| `createdAt`       | `string`           | ISO 8601 submission timestamp                                 |
| `finishedAt`      | `string` \| `null` | ISO 8601 completion timestamp, or `null` if still in progress |

### Pagination Fields

| Field        | Type     | Description                                 |
| ------------ | -------- | ------------------------------------------- |
| `page`       | `number` | Current page number                         |
| `limit`      | `number` | Items per page                              |
| `total`      | `number` | Total number of batch jobs for your account |
| `totalPages` | `number` | Total pages at the current `limit`          |

***

## Errors

| Code  | Reason                     |
| ----- | -------------------------- |
| `401` | Missing `x-api-key` header |
| `403` | Invalid or expired API key |

***

<CardGroup cols={2}>
  <Card title="Get Batch Status" icon="magnifying-glass" href="/api-reference/scraping/batch-scrape-status">
    Fetch full results for a specific batch
  </Card>

  <Card title="Submit a Batch" icon="plus" href="/api-reference/scraping/batch-scrape">
    Start a new batch job
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /batch/scrape
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:
    get:
      tags:
        - Batch Scraping
      summary: List Batch Jobs
      description: >-
        Retrieve a paginated list of all batch scrape jobs for your account,
        ordered by most recent first.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-based)
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: Number of jobs per page. Maximum 50
      responses:
        '200':
          description: Paginated list of batch jobs
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                          format: uuid
                        status:
                          type: string
                          enum:
                            - pending
                            - running
                            - completed
                            - failed
                            - cancelled
                        totalUrls:
                          type: integer
                        completedCount:
                          type: integer
                        failedCount:
                          type: integer
                        outputFormat:
                          type: string
                        scrapingChannel:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        finishedAt:
                          type:
                            - string
                            - 'null'
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
                      totalPages:
                        type: integer
        '401':
          description: Missing x-api-key header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      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

````