Pagination, sorting & filters

List envelopes, page parameters, totals, sorting, and filter validation.

Standard list endpoints return the following:

{
  "object": "list",
  "data": [
    {"id": "cus_123", "object": "customer", "data": {}}
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_count": 137,
    "has_more": true
  }
}

Parameters

The effective offset is (page - 1) * limit. Malformed pagination parameters are rejected with 422 validation_error before reaching the endpoint — use positive integers for both fields.

Completion

Clients should page until pagination.has_more is false.

pagination.total_count describes the full filtered result set, not just the current page. It can be used to show progress, but clients should still rely on has_more for completion because filters and records may change while paging.

Sorting

Endpoints that support sorting use a sort query parameter:

• sort=created_at sorts ascending.
• sort=-created_at sorts descending.
• Multiple fields may be comma-separated when the endpoint allows them.

Sort fields are allowlisted per endpoint. Unknown fields return 422 validation_error with a sort entry in details or errors.

Filters

Filter validation is strict: invalid enum, status, and date filters return 422 validation_error instead of being silently ignored. Date filters use ISO YYYY-MM-DD unless the endpoint documents a full timestamp. The available filters for each list endpoint are documented in the API reference.