---
title: "List bulk jobs"
description: "The shop bulk jobs, newest first, as the Bulk actions page lists them: kind, status, progress, count and the download link of finished PDF jobs. status values: preparing (Preparing), pending (Queued), processing (Running"
url: https://docs.invoicefalcon.com/v3-reference/documents/list-bulk-jobs/
api: "API v3 reference"
method: GET
path: "/documents/bulk"
---

# List bulk jobs

`GET https://app.invoicefalcon.com/api/v3/external/documents/bulk`

The shop bulk jobs, newest first, as the Bulk actions page lists them: kind, status, progress, count and the download link of finished PDF jobs.

`status` values: `preparing` (Preparing), `pending` (Queued), `processing` (Running), `finalizing` (Finishing), `complete` (Complete), `failed` (Failed), `cancelled` (Cancelled).

`kind` values: `print` (PDF print / download), `send` (Email send), `csv` (CSV export).

## Query parameters

- `status` (string): Only jobs in this status (pending, processing, complete, failed, cancelled). One of: `preparing` (Preparing), `pending` (Queued), `processing` (Running), `finalizing` (Finishing), `complete` (Complete), `failed` (Failed), `cancelled` (Cancelled). One of: `preparing`, `pending`, `processing`, `finalizing`, `complete`, `failed`, `cancelled`.
- `page` (integer): 1-based page number.
- `per_page` (integer): Rows per page, default 25, max 100.

## Returns

- `items` (array of objects, required)
  - `job_id` (integer): e.g. `13`
  - `kind` (string): e.g. `print`
  - `status` (string): e.g. `pending`
  - `progress` (integer): e.g. `0`
  - `count` (integer): e.g. `1`
  - `failure_reason` (string, nullable)
  - `download_url` (string, nullable)
  - `delivery_method` (string): e.g. `print`
  - `processing_type` (string, nullable)
  - `template_name` (string): e.g. `default`
  - `from` (object, nullable)
  - `to` (string, nullable)
  - `created_at` (string): e.g. `2026-11-10T08:35:18Z`
  - `updated_at` (string): e.g. `2026-11-10T08:35:18Z`
- `page` (object, required): Offset paging of a list (`page`, `per_page` query params).
  - `number` (integer, required): 1-based page number.
  - `size` (integer, required): Rows per page, max 100.
  - `total` (integer, required): Rows across all pages.
  - `total_pages` (integer, required): e.g. `1`

Rate limit: this call costs 1 point ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Examples

### List bulk jobs

```sh
curl "https://app.invoicefalcon.com/api/v3/external/documents/bulk" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

### List bulk jobs filtered by status

```sh
curl "https://app.invoicefalcon.com/api/v3/external/documents/bulk?status=preparing" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

One page of rows.

```json
{
  "items": [
    {
      "job_id": 13,
      "kind": "print",
      "status": "pending",
      "progress": 0,
      "count": 1,
      "failure_reason": null,
      "download_url": null,
      "delivery_method": "print",
      "processing_type": null,
      "template_name": "default",
      "from": null,
      "to": null,
      "created_at": "2026-11-10T08:35:18Z",
      "updated_at": "2026-11-10T08:35:18Z"
    }
  ],
  "page": {
    "number": 1,
    "size": 25,
    "total": 1,
    "total_pages": 1
  }
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

