> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tables rows list

> List rows in a table, optionally filtered.

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`](/cli/reference/tables-rows-get).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay tables rows list <tableId> [--filter <expr>] [--limit <n>] [--cursor <token>]
```

## Arguments

| Argument  | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `tableId` | Table id (regular or archive), e.g. `tbl_abc123`. Required. |

## Flags

| Flag               | Description                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `--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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
}
```

| Field              | Type   | Description                                                                                                        |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `data[].id`        | string | Row id.                                                                                                            |
| `data[].updatedAt` | string | Last-updated timestamp.                                                                                            |
| `data[].cells`     | object | Map of column id to a cell object (see below).                                                                     |
| `cursor`           | string | Present 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`:

| Status                                                            | Fields                                                                           | Meaning                                                           |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `success`                                                         | `value` (computed value), `fields` (object \| null), `isStale` (optional `true`) | The cell has a computed value; structured content is in `fields`. |
| `error`                                                           | `error` (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

| Code               | Exit | Notes                                                                                                                                                           |
| ------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation_error` | 2    | A 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_found`        | 6    | No table with that id in this workspace.                                                                                                                        |
| `auth_forbidden`   | 3    | The API key lacks the `cli:all` scope, or you cannot read this table.                                                                                           |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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'
```