---
title: Pagination and filtering
description: page and per_page, the meta block on every collection, filter[...] parameters including CSV values, and which lists are not paginated.
canonical_url: "https://cascades.crscreditapi.com/docs/concepts/pagination-and-filtering"
doc_version: "1.0.0"
last_updated: "2026-09-23T19:55:02Z"
source: docs/concepts/pagination-and-filtering.md
---

# Pagination and filtering

Every list endpoint pages the same way and reports the same metadata, so one client helper covers all of them.

## How do I page?

`page` (default `1`) and `per_page` (default `25`, maximum `100` — larger values are clamped, not rejected). A `page` past the end is clamped to the last page rather than returning an empty array; a non-numeric or negative `page` is treated as `1`.

```http
GET /api/v1/executions?page=2&per_page=50
```

```json
{
  "data": [ … ],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total_count": 142,
    "total_pages": 3,
    "object": "execution",
    "request_id": "7d4c2f48-…"
  }
}
```

Pagination is offset-based; there are no cursor or `Link` headers. Sort order is fixed per endpoint (newest first for most lists, `row_index` order for batch rows, `created_at` ascending for review events).

## How do I filter?

Filters are `filter[<field>]` query parameters. Where a field accepts several values, pass them as a comma-separated list:

```http
GET /api/v1/executions?filter[status]=running,waiting&filter[workflow_id]=27
GET /api/v1/webhook_deliveries?filter[status]=failed,dead
GET /api/v1/workflows?filter[active]=true
```

| Endpoint | Filters |
|---|---|
| `GET /workflows` | `active`, `use_case`, `trigger_type` |
| `GET /workflow_templates` | `featured`, `category` |
| `GET /executions` | `workflow_id`, `status` (CSV), `needs_human_review`, `review_status` (CSV), `batch_execution_id`, `execution_key`, `external_reference` |
| `GET /batches` | `status` (CSV), `workflow_id`, `external_reference` |
| `GET /batches/{id}/executions` | `status` (CSV) |
| `GET /webhook_deliveries` | `webhook_subscription_id`, `event_type`, `status` (CSV) |

CSV filters are validated: a value outside the allowed set (an execution status that does not exist, say) returns `422 validation_failed` with a `details` entry naming the field. Booleans accept `true`/`false`.

## Which lists are not paginated?

Artifact lists (`GET /executions/{id}/report_artifacts`, `…/notice_artifacts`) and `GET /workflows/{id}/test_cases` return the complete collection in one response; `page` and `per_page` are ignored there.

## Related

- [Executions](/docs/concepts/executions)
- [Keys, scopes and rate limits](/docs/concepts/scopes-and-keys) — stay under the per-minute limit when walking a large collection

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.