# List the account's bulk consistency runs

`GET /api/v1/consistency/bulk`

- Authentication: Secret API key as a bearer token
- Billing: Free.
- Group: Consistency

Every bulk consistency run this account has started, newest first, 100 per page. A job id is handed out once, at creation, and everything about a run hangs off it — its counts, its results, its cancel and resume calls — so this is how a caller that lost one finds the run again.

`status`, `since` and `until` are optional and combine; a bare date in `until` means the whole of that day, and an unknown status or an unparseable date is a `422` rather than an empty page. The webhook secret is never among the rows: it is returned once, at creation.

Runs are kept as long as the lookup history, and `meta.retention_days` says how long that is — a run older than that is deleted with its files and cannot be listed.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string | no | Only runs in this status. One of: queued, processing, completed, failed, cancelled. |
| `since` | query | string | no | Only runs created at or after this date or timestamp. |
| `until` | query | string | no | Only runs created at or before this. A bare date means the whole of that day. |
| `page` | query | integer | no | The page to return. Default: 1. |

## Example request

```bash
curl https://spaw.co/api/v1/consistency/bulk \
  -H "Authorization: Bearer sk_live_…"
```

## Responses

### 200 — One page of runs, newest first.

```json
{
    "success": true,
    "data": {
        "jobs": [
            {
                "id": 41,
                "status": "completed",
                "total": 900,
                "duplicate_count": 3,
                "processed": 900,
                "flagged": 61,
                "unflagged": 802,
                "uncompared": 37,
                "credits_used": 2410,
                "stopped_reason": null,
                "cancel_requested": false,
                "country": "GB",
                "webhook_status": null,
                "webhook_detail": null,
                "created_at": "2026-09-10T11:30:00+00:00",
                "finished_at": "2026-09-10T11:36:12+00:00"
            }
        ]
    },
    "meta": {
        "page": 1,
        "per_page": 100,
        "total": 1,
        "retention_days": 30
    }
}
```

### 401 — The key is missing, malformed, or revoked.

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 422 — The request body could not be validated; `error.errors` lists the fields.

```json
{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 429 — Over 5 requests per second for the key. Retry after the limit resets.

```json
{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `VALIDATION_FAILED` — https://spaw.co/docs/errors/VALIDATION_FAILED
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/list-consistency-bulk-jobs · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api