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

# List roster rows with cursor pagination

`GET /roster-records/{rosterId}`

Returns a page of individual data rows belonging to one roster job.

**When to use:** call this to stream through a large roster without needing to know how many rows there are; use `GET /roster-records/{rosterId}/paged` instead when you need `totalCount` and `totalPages`, for example to render a numbered page selector.

**Preconditions:** supply the `tenant-id` header and the `rosterId` of an existing roster job. Leave `cursor` unset on the first call, then pass the `nextCursor` from each response to retrieve the following page; `nextCursor` is absent once the last page has been reached. `size` controls how many rows come back and defaults to 50, with values above 1000 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.

**What you get back:** the rows for this page in `data`, the `nextCursor` to pass on the following call, the effective `pageSize`, and `hasMore`. Each row carries its `rowId` - the identifier used as `recordKey` when saving draft edits. Read-only; no state is mutated.

## Path parameters

- `rosterId` string, required

## Query parameters

- `cursor` string
- `size` integer
- `statuses` string

## Headers

- `tenant-id` string, required

## Response `200`

One page of roster rows, with the cursor needed to request the next page.

- RosterRowsPage — One page of roster rows, navigated with a forward cursor.
  - `data` RosterRowItem[] — The roster rows in this page, in cursor order.
    - `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.
  - `nextCursor` string, nullable — Cursor to pass as the cursor parameter to fetch the next page. Null (serialized explicitly, not omitted) once the last page has been reached - check `hasMore` or a null `nextCursor` to stop paging.
  - `pageSize` integer — The requested page size this page was fetched with - not the number of rows actually returned, which can be smaller on the last page (count `data` for that). Defaults to 50 and is capped at 1000.
  - `hasMore` boolean — True when more rows remain after this page.

## 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)