Read rows
GET/v1/db/{project_id}/{table}
Query a table with filters, order, pagination and joins. PostgREST under the hood, RLS applied automatically.
Headers#
| Header | Required | Value |
|---|---|---|
apikey | yes | Project API key (anon or service_role). X-API-Key is accepted too. |
Authorization | no | Bearer <JWT>. Without it, the request runs as anon |
Query parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
select | string | no | Columns to return. * by default. Relationship embed (FK): posts(*), author:authors(name). |
order | string | no | captured_at.desc · name.asc. NULL placement (.nullsfirst/.nullslast) is only honored on MongoDB in its native form (asc.nullsfirst, desc.nullslast); the other two combinations are refused in 400 rather than issuing an order different from that requested. |
limit | integer | no | Max number of lines. Default 1000, max 1000 — beyond that, the response is capped and meta.per_page indicates the limit actually applied. |
offset | integer | no | Paging offset. Only pagination available on PostgREST, the nominal engine of a Postgres project. |
cursor | string | no | aura-db only (MongoDB, or Postgres with PostgREST disabled) — not available on PostgREST, which responds 400 by naming offset. Pagination keyset: return the opaque meta.next_cursor of the previous page as is. Stable, without dup/skip (int/uuid/text). Aligns with sort_by. |
count | enum | no | exact, planned, or estimated. No counting is done by default. This is the portable form: on the aura-db path, only this query parameter is read — a Prefer: count=exact header there would be ignored (it is only honored by PostgREST). |
<column>.<op> | filter | no | Filters: value.gt.24, status.eq.active, name.like.%alice%, tags.cs.{urgent}. |
To know#
Relationship embed (FK) via select: author:authors(name) (LEFT JOIN — rows without relationships return null). Inner-join filtering is supported with !inner: e.g. author:authors!inner(name)&author.country=eq.FR.
The Range header is not a universal alternative paging: the aura-db path (MongoDB project, or Postgres with PostgREST disabled) only reads the query parameters and ignores it. It only has effect if the request reaches PostgREST. Use limit/offset.
The answer is wrapped : { data, meta }, never a bare array. On the PostgREST path, meta only contains total (and only if a count has been requested); on the aura-db path it also carries per_page and next_cursor.
numeric/decimal columns are serialized as JSON number by default in PostgREST and typed as number by @aurabase/gen. When exact arbitrary precision (> 15 significant digits) is required, cast the expression (amount::text in SQL / view) or pass --numeric-as-string (numericAsString: true) to @aurabase/gen.