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.
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.