Pagination and Filtering
Preserve opaque cursors and follow each generated query schema
Each generated operation defines its own pagination shape. VRPlatform uses both page/limit responses and opaque cursors depending on the resource.
Opaque Cursors
Opaque-cursor endpoints include GET /audit/timeline, GET /audit/events,
GET /partner/audit-events, and GET /teams/issues.
Pass nextCursor back unchanged as cursor. Do not decode it, generate your
own, compare it lexically, or reuse it after changing filters. A null cursor or
hasMore=false ends a finite traversal. Polling clients retain the last
non-null cursor as described by the operation's canonical guide.
Page And Offset
Where declared, send the operation's page, limit, or offset fields and
render its returned totals. Do not add paging fields to an operation that does
not declare them.
For standard page/limit collections, limit is an integer from 1 to 250
(default 100), page is an integer starting at 1, and offset is a
nonnegative integer. Omitting both page and offset starts at page 1.
Fractional, negative, or unsafe numeric values return 400 BAD_REQUEST.
The resulting page and offset must also fit JavaScript's safe integer range.
An explicit offset selects the rows even when page is supplied. When
page is omitted, the response page is floor(offset / limit) + 1.
Otherwise, the response retains the supplied page. Without offset, rows
start at (page - 1) * limit.
For example, ?limit=25&offset=50 returns rows starting at offset 50 and
reports page 3; ?limit=25&page=4&offset=50 selects the same rows and reports
page 4.
Sorting
Where declared, use the generated operation's signed sort enum. An
unprefixed field sorts ascending and a - prefix sorts descending. For
example, use sort=date for oldest first and sort=-date for newest first.
Omitting sort uses the default published by that operation.
Text fields sort case-insensitively. Nullable sort fields place nulls last in
both directions, and a final ID tie-breaker keeps page traversal deterministic.
The removed sortBy and sortDirection query parameters are rejected, as are
direction-suffix values such as created_desc.
Filters
- Query parameters are strict.
- Comma-separated arrays, repeated form values, booleans, dates, and ranges follow the generated OpenAPI serialization metadata.
- Keep filter state with its cursor or page state.
- Reset pagination after a filter, sort, view, or team change.
- Treat IDs as team-scoped even when their format is globally unique.
For a concrete cursor workflow, see Portfolio health or Audit Events.