---
title: "List roster rows with offset pagination and totals"
method: GET
path: "/roster-records/{rosterId}/paged"
tags: ["RosterRecord"]
---

# List roster rows with offset pagination and totals

`GET /roster-records/{rosterId}/paged`

Returns a page of individual data rows belonging to one roster job, together with the total number of matching rows.

**When to use:** call this when the caller needs to show how many rows exist or jump directly to an arbitrary page, such as a numbered page selector in a table; use the cursor-based `GET /roster-records/{rosterId}` instead when streaming through a large roster, since computing totals costs more.

**Preconditions:** supply the `tenant-id` header and the `rosterId` of an existing roster job. `page` is zero-based and defaults to 0; `size` controls rows per page, defaults to 50, and values above 1000 are capped at 1000.

**Filtering:** pass `statuses` to restrict the page to particular row states, as a comma-separated list drawn from `PENDING`, `IN_PROGRESS`, `VALIDATION_IN_PROGRESS`, `PRE_PROCESSING`, `VALIDATION_FAILED`, `VALIDATED`, `COMPLETED`, `FAILED`, and `CANCELLED`; omit it to receive rows in every state. The totals reflect the filter.

**What you get back:** the rows for this page in `data`, the echoed `page` and `size`, `totalCount` and `totalPages` across the filtered set, and `hasMore`. Read-only; no state is mutated.

## Path parameters

- `rosterId` string, required

## Query parameters

- `page` integer
- `size` integer
- `statuses` string

## Headers

- `tenant-id` string, required

## Response `200`

One page of roster rows, with the total row and page counts for the filtered set.

- RosterRowsOffsetPage — One page of roster rows, navigated by page number, with totals for the filtered set.
  - `data` RosterRowItem[] — The roster rows in this page.
    - `rowId` string — Stable identifier of this row within the roster. Pass it as recordKey when saving draft edits, and use it to correlate Smart Fix suggestions back to the row they belong to.
    - `status` string — Processing state of this row. One of PENDING, IN_PROGRESS, VALIDATION_IN_PROGRESS, PRE_PROCESSING, VALIDATION_FAILED, VALIDATED, COMPLETED, FAILED, or CANCELLED. Only rows in VALIDATION_FAILED accept draft edits.
    - `data` JsonNode
      - `empty` boolean
      - `valueNode` boolean
      - `containerNode` boolean
      - `missingNode` boolean
      - `array` boolean
      - `object` boolean
      - `nodeType` 'ARRAY' | 'BINARY' | 'BOOLEAN' | 'MISSING' | 'NULL' | 'NUMBER' | 'OBJECT' | 'POJO' | 'STRING'
      - `pojo` boolean
      - `number` boolean
      - `integralNumber` boolean
      - `floatingPointNumber` boolean
      - `short` boolean
      - `int` boolean
      - `long` boolean
      - `float` boolean
      - `double` boolean
      - `bigDecimal` boolean
      - `bigInteger` boolean
      - `textual` boolean
      - `boolean` boolean
      - `null` boolean
      - `binary` boolean
    - `createdAt` string — When the row was first stored, as an ISO-8601 timestamp in UTC.
    - `updatedAt` string — When the row was last changed, as an ISO-8601 timestamp in UTC. Updated when draft edits are saved or validation re-runs.
  - `page` integer — Zero-based number of the page returned.
  - `size` integer — Number of rows requested per page. Defaults to 50 and is capped at 1000.
  - `totalCount` integer — Total rows matching the request across every page, after any status filter is applied.
  - `totalPages` integer — Total number of pages available at the current page size.
  - `hasMore` boolean — True when more pages remain after this one.

## Other responses

- `401` — Returned when the request carries no valid authentication.
- `403` — Returned when the caller lacks the READ_ROSTER permission for this tenant.
- `500` — Returned when the rows cannot be read from the underlying store. Retry; if the failure persists, contact support.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)