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

# Reading data

> Filter, sort, paginate, and export enriched table rows with the v2 API.

[`GET /api/v2/tables/{tableId}/rows`](/agents/reference/list-rows) returns a
table's rows with support for filtering, sorting, cursor pagination, and CSV
export. Reads are free.

## Basic request

```bash theme={null}
curl "https://origami.chat/api/v2/tables/TABLE_ID/rows" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"
```

Rows come back in the standard list envelope, plus a top-level `total` (the
filtered row count for the whole query, across all pages). Each row is a typed
object keyed by column slug.

```json theme={null}
{
  "object": "list",
  "items": [
    {
      "object": "row",
      "id": "a1b2c3d4-…",
      "cells": {
        "company-name": { "type": "scalar", "value": "Acme Corp" },
        "website": { "type": "scalar", "value": "acme.com" },
        "ceo-email": { "type": "value", "value": "ceo@acme.com" }
      }
    }
  ],
  "nextCursor": "eyJ…",
  "total": 150,
  "url": "/api/v2/tables/TABLE_ID/rows"
}
```

By default the table's saved filters and sort order apply — the same view you see
in the Origami dashboard.

### Typed vs flat cells

Cells are polymorphic by default: `scalar` for input columns, `value` (with run
metadata where present) for enrichments, and `sequence` for outreach columns.
For the simpler v1-style `{ slug: value }` rows, pass `?cells=flat`.

```bash theme={null}
curl "https://origami.chat/api/v2/tables/TABLE_ID/rows?cells=flat" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"
```

## Pagination

Pagination is cursor-based. Read the first page, then pass its `nextCursor` back
as the `cursor` parameter to get the next one. Stop when `nextCursor` is `null`.

```bash theme={null}
curl "https://origami.chat/api/v2/tables/TABLE_ID/rows?limit=200&cursor=eyJ…" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"
```

`limit` defaults to 50. This endpoint allows up to **200** rows per page (most
other list endpoints cap at 100). There is no `page` or `pageSize`.

## Filtering

Pass a JSON-encoded array of filter objects in the `filters` parameter. Each
filter uses a column **slug**, an `operator`, and a `value`.

```bash theme={null}
curl -G "https://origami.chat/api/v2/tables/TABLE_ID/rows" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  --data-urlencode 'filters=[{"column":"website","operator":"is_not_empty","value":""}]'
```

Available operators: `contains`, `not_contains`, `equals`, `not_equals`,
`is_empty`, `is_not_empty`, `greater_than`, `greater_than_or_equal`,
`less_than`, `less_than_or_equal`. An unknown column slug returns
`UNKNOWN_COLUMN`.

## Sorting

Pass a JSON-encoded sort object with a column **slug** and `direction`.

```bash theme={null}
curl -G "https://origami.chat/api/v2/tables/TABLE_ID/rows" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  --data-urlencode 'sort={"column":"quality-score","direction":"desc"}'
```

## Bypassing saved defaults

By default the API applies the table's saved filters and sort order. Set
`defaults=false` to read all rows unfiltered, in insertion order.

```bash theme={null}
curl "https://origami.chat/api/v2/tables/TABLE_ID/rows?defaults=false" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"
```

## CSV export

Set `format=csv` to stream the (flat) rows as a CSV file instead of JSON —
column names as headers, ready for a spreadsheet.

```bash theme={null}
curl "https://origami.chat/api/v2/tables/TABLE_ID/rows?format=csv&limit=200" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -o export.csv
```

## Reading a single row or cell

To read one row, use
[`GET /api/v2/tables/{tableId}/rows/{rowId}`](/agents/reference/get-row). To read
a single cell — with its run metadata — use
[`GET /api/v2/tables/{tableId}/rows/{rowId}/cells/{columnId}`](/agents/reference/get-cell).

<Note>
  This page covers the v2 read endpoint. The deprecated v1 `GET /tables/{tableId}/rows`
  (offset pagination, flat rows) still works — see the
  [migration guide](/api-v1-to-v2-migration).
</Note>