Pagination and Filtering

Collection endpoints return a data array and, when paginated, a meta object.

{
  "success": true,
  "data": [
    {
      "release_id": "7f6d2a4b-8c41-4e2d-9c5e-13a2b7c8d904",
      "title": "Midnight Atlas",
      "status": "draft"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1,
    "from": 1,
    "to": 1
  }
}

The staging-only DDEX and enterprise webhook collection endpoints currently use a different envelope. Their top-level data value is the paginator, records are in data.data, and page fields such as current_page, last_page, per_page, and total are siblings of that inner record array.

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "reference": "3bc1f628-60af-4db2-b984-321c1525df20",
        "status": "testing"
      }
    ],
    "last_page": 1,
    "per_page": 10,
    "total": 1
  }
}

Use the envelope shown by each operation rather than assuming the nesting is identical across endpoint families.

Common query fields

Query field matrix

Client behavior

• Treat missing meta as a non-paginated response.
• Use page values of 1 or greater and read the returned per_page; do not assume every endpoint has the same default.
• Request no more than 100 records per page.
• Stop fetching when current_page equals last_page.
• Preserve the same search, status, and sort values across pages.
• Do not infer access from totals. Permission rules can change what each user sees.

Common questions

Why does one endpoint family nest its records differently? The staging-only DDEX and enterprise webhook collections return the paginator as the top-level data value, with records in data.data. Read the envelope each operation documents rather than assuming one shape site-wide.

What is the maximum page size? 100. Values above it are clamped down and values below 1 are clamped up to 1. Defaults vary per endpoint, so read the returned per_page.

How do I know I have reached the last page? Stop when current_page equals last_page. A missing meta object means the response is not paginated.

Can I use total to check what a user can access? No. Permission rules change what each user sees, so totals are not an access signal.