Skip to main content
List rows in a table, paginated in approximate creation order. Narrow the results with one or more --filter conditions, which are ANDed together. Fetch a single row with clay tables rows get. 
clay tables rows list <tableId> [--filter <expr>] [--limit <n>] [--cursor <token>]

​
Arguments

ArgumentDescription
tableIdTable id (regular or archive), e.g. tbl_abc123. Required.

​
Flags

FlagDescription
--filter <expr>Narrow results. Repeatable; conditions are ANDed. Format <columnId>=<value>, matched exactly on basic columns only.
--limit <n>Maximum rows to return per page. Must be in range 1–100. Defaults to 20.
--cursor <token>Resume from a previous response’s cursor to fetch the next page.
With no --filter, every row is listed. A paginated listing covers the rows that existed when its first page was fetched; rows added afterwards need a fresh listing.

​
Archive tables

Archive tables support only a single-value search on the searchable field: pass --filter f_archive_index=<v>. Listing without a filter and multiple filters are rejected. Archive results are a single capped page with no cursor. Search values are limited to 255 characters — the archive index stores a 255-character prefix, so search for the first 255 characters of a longer value.

​
Output

{
  "data": [
    {
      "id": "rec_1",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "cells": {
        "col_email": { "status": "success", "value": "jane@acme.com", "fields": null }
      }
    }
  ],
  "cursor": "next_page_token"
}
FieldTypeDescription
data[].idstringRow id.
data[].updatedAtstringLast-updated timestamp.
data[].cellsobjectMap of column id to a cell object (see below).
cursorstringPresent when more rows are available (regular tables only). Pass it back via --cursor. Omitted on the last page.

​
Cell shape

Each cell is discriminated on status:
StatusFieldsMeaning
successvalue (computed value), fields (object | null), isStale (optional true)The cell has a computed value; structured content is in fields.
errorerror (string, optional)The cell errored; error carries the message.
running, queued, retry, rate_limited, awaiting_callback—The cell is still being computed.
empty—The cell has no value yet.

​
Errors

CodeExitNotes
validation_error2A malformed --filter, an unknown column, a value filter on a non-basic column, an unsupported pattern on an archive table, or --limit out of range (1–100).
not_found6No table with that id in this workspace.
auth_forbidden3The API key lacks the cli:all scope, or you cannot read this table.

​
Examples

clay tables rows list tbl_abc123 | jq -r '.data[].id'
clay tables rows list tbl_abc123 --filter col_email=acme.com | jq '.data | length'
clay tables rows list tbl_abc123 --filter col_email=acme.com --filter col_stage=lead | jq -r '.data[].id'
clay tables rows list tbl_archive --filter f_archive_index=acme.com | jq -r '.data[].id'