---
title: "list rows"
method: GET
path: "/datasets/{id}/rows"
tags: ["Dataset CRUD"]
---

# list rows

`GET /datasets/{id}/rows`

## Request

- Base URL: `https://api.riveterhq.com/v1`
- URL: `https://api.riveterhq.com/v1/datasets/{id}/rows`
- Auth: HTTP bearer

The dataset's rows in position order, each with its `input` values, its `cells` by output column name (`value`, `state`, `sources`), and the `credits` spent on it. Page with `limit` (max 1,000) and `cursor`; `updated_since` returns only rows changed since then.

Two parameters make a read small enough to take a whole dataset in a few calls: `columns` (comma-separated names) keeps only those columns in `input` and `cells`, and `compact=true` answers the values-only shape (`CompactDatasetRow`: `position`, `input`, `cells` as `{ "<column>": value }`, a cell without a value null). A 1,000-row page of one column in that shape is a few tens of kilobytes. For counts over a column, [GET /datasets/{id}/summary](#tag/dataset-crud/get/datasets/{id}/summary) needs no rows at all.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `cursor` integer
- `updated_since` string, date-time
- `columns` string
- `compact` boolean

## Response `200`

One page of rows

- object
  - `rows` union[]
    - union
      - DatasetRow
        - `id` string: row_...
        - `position` integer: Insertion order, from 1 (the row number a user sees); stable, and the paging cursor
        - `input` object: Input values by column name
        - `cells` object: Cells by output column name (every output column is present; in a run's `output.rows`, only the columns the fill covered)
        - `credits` number: Credits fills have charged for this row so far (each row run counted once)
        - `not_found_reason` string, nullable: The agent's one sentence on what it could not find on this row and why, from its last successful run; null when it found every column or has not run
        - `created_at` string, date-time
        - `updated_at` string, date-time
      - CompactDatasetRow: A row as `compact=true` answers it on GET /datasets/{id}/rows — the values alone. Address the row by `position` elsewhere.
        - `position` integer: Insertion order, from 1
        - `input` object: Input values by column name (the `columns` named, else every input column)
        - `cells` object: Cell values by output column name (the `columns` named, else every output column)
  - `next_cursor` integer, nullable: Pass back as `cursor` for the next page; null on the last page
  - `row_count` integer

## Other responses

- `400`: The request is malformed or names a conflicting parameter combination
- `401`: Missing or invalid API key (`request_status` body — see the AuthError schema)
- `403`: The API key's account may not access this resource or endpoint (`forbidden`), or the account has not migrated to Datasets yet (`feature_not_enabled` — open Datasets in the app and click "Migrate to Datasets")
- `404`: No resource with that id on this account

## Changes

- **2026-11-13** `fac56b649559`: 2 info
  - api tag `Dataset CRUD` added
  - api tag `Datasets` removed
- **2026-10-30** `dcb4d45ade1a`: 6 info
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `400` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `403` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `404` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/upfront` to the response with the `400` status
  - …2 more
- **2026-10-30** `9db88e317ebe`: 2 breaking, 8 warning, 2 info
  - added `#/components/schemas/DatasetRow, #/components/schemas/CompactDatasetRow` to the `rows/items/` response property `oneOf` list for the response status `200`
  - the `rows/items/` response's property type changed from `object` to no type for status `200`
  - removed the optional property `rows/items/cells` from the response with the `200` status
  - removed the optional property `rows/items/created_at` from the response with the `200` status
  - …8 more
- **2026-10-19** `76aabcc5686b`: 2 info
  - api tag `Datasets` added
  - api tag `Datasets (beta)` removed
- **2026-10-13** `029668894d33`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/riveterhq/apis/riveter-api/changes/datasets/:id/rows/get.md)

---

[API](https://skmtc.dev/riveterhq/apis/riveter-api.md) - [All operations](https://skmtc.dev/riveterhq/apis/riveter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/riveterhq/apis/riveter-api/revisions/fac56b649559?raw)