Concepts

Pagination and filtering

page and per_page, the meta block on every collection, filter[...] parameters including CSV values, and which lists are not paginated.

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.

Executions
Keys, scopes and rate limits — stay under the per-minute limit when walking a large collection

How do I page?

How do I filter?

Which lists are not paginated?

Related