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

# list_rows

> Read rows from a table with optional filters, sorting, and paging.

Reads rows from one table. By default it returns the 25 oldest rows.

| | |
| - | - |
| Scope | `mcp:read` |
| Annotations | `readOnlyHint: true` |

## Parameters

<ParamField body="projectId" type="string" required>
  Project id from `list_projects`.
</ParamField>

<ParamField body="table" type="string" required>
  Table name.
</ParamField>

<ParamField body="filters" type="object[]">
  Conditions that every returned row must match. See [Filters](/mcp/filters).
</ParamField>

<ParamField body="orderBy" type="object">
  Sort order. Without it, rows are sorted by `created_at`, oldest first.

  <Expandable title="properties">
    <ParamField body="col" type="string" required>
      Column to sort by.
    </ParamField>

    <ParamField body="ascending" type="boolean" default="true">
      `false` sorts in descending order.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="limit" type="integer" default="25">
  Rows to return, from 1 to 100. Values above 100 return 100 rows.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Rows to skip, for paging. Must be 0 or more.
</ParamField>

## Result

An array of row objects keyed by column name, including `id` and `created_at`. See [value formats](/mcp/responses-and-errors#value-formats-in-results).

## Example

```json Arguments theme={null}
{
  "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz",
  "table": "books",
  "filters": [
    { "col": "finished", "op": "eq", "value": true },
    { "col": "rating", "op": "gte", "value": 4 }
  ],
  "orderBy": { "col": "rating", "ascending": false },
  "limit": 10
}
```

```json Result theme={null}
{
  "data": [
    {
      "id": "0b7c1f7e-6f0e-4d3a-9a51-2f7c3d1b8e44",
      "created_at": "2026-10-14T16:02:11.482Z",
      "title": "Piranesi",
      "author_id": "c3f1e8a2-7b4d-4e19-a0c6-5d2b9f8e1a37",
      "finished": true,
      "rating": 5,
      "details": { "tags": ["fiction", "fantasy"] }
    },
    {
      "id": "8e2d4b6a-1c3f-4a5e-9b7d-0f2e4c6a8b1d",
      "created_at": "2026-10-14T16:02:11.482Z",
      "title": "The Dispossessed",
      "author_id": "9a4c2e6b-8d1f-4b3a-a5c7-e9f1d3b5a7c2",
      "finished": true,
      "rating": 4,
      "details": null
    }
  ]
}
```

## Sorting and paging

* With `orderBy`, `NULL` values sort last in both directions, and ties are broken by `id`.
* Without `orderBy`, rows sort by `created_at`, then `id`.
* To page, keep the same filters and order and increase `offset` by `limit`. A page shorter than `limit` is the last page.

```json Second page of 100 theme={null}
{ "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz", "table": "books", "limit": 100, "offset": 100 }
```

## Errors

| Code | When |
| - | - |
| `ACCESS_DENIED` | The project doesn't exist or you can't access it |
| `VALIDATION` | Unknown table or column, an invalid filter, `limit` below 1, a negative `offset`, or a query that ran longer than 5 seconds |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.