# Query a database

`POST /v1/databases/{databaseId}/query`

Returns one window of a view's rows (filtered, sorted, grouped), with the total and group counts. Pass viewId for a saved view, or view for an ad-hoc one (both: view overrides). uniqueId values are numbers (shown as prefix-number, e.g. LYD-12); filters take 12 or "LYD-12".

Scope: `docs:read`.

## Request

```bash
curl -X POST "https://api.lydie.co/v1/databases/01JCQ3V5MZ8G4ZK2X7T9R6N1PB/query" \
  -H "Authorization: Bearer $LYDIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Path parameters

- `databaseId` (ULID, required)

## Body

- `viewId` (ULID, optional)
- `view` (object, optional)
  - `type` (string, optional): One of: `table`, `board`, `list`, `calendar`, `gallery`. Default: `"table"`.
  - `config` (ViewConfigPatchInput, optional): Default: `{}`.
    - `filter` (FilterNode, optional, nullable)
    - `sorts` (object[], optional)
      - `propertyId` (ULID, required)
      - `direction` (string, optional): One of: `asc`, `desc`. Default: `"asc"`.
    - `groupBy` (GroupByInput, optional, nullable)
      - `propertyId` (ULID, required)
      - `direction` (string, optional): One of: `asc`, `desc`. Default: `"asc"`.
      - `order` (string[], optional)
      - `hideEmpty` (boolean, optional): Hide groups with no rows (board columns).
      - `dateBucket` (string, optional): Date grouping; default month. One of: `day`, `week`, `month`, `year`.
      - `collapsed` (string[], optional)
    - `subGroupBy` (GroupByInput, optional, nullable): Board swimlanes.
      - `propertyId` (ULID, required)
      - `direction` (string, optional): One of: `asc`, `desc`. Default: `"asc"`.
      - `order` (string[], optional)
      - `hideEmpty` (boolean, optional): Hide groups with no rows (board columns).
      - `dateBucket` (string, optional): Date grouping; default month. One of: `day`, `week`, `month`, `year`.
      - `collapsed` (string[], optional)
    - `columns` (ViewColumnInput[], optional)
      - `propertyId` (ULID, required)
      - `visible` (boolean, optional): Default: `true`.
      - `width` (integer, optional): (20–2000)
    - `limit` (integer, optional, nullable): (≥ 1)
    - `summaries` (object, optional): propertyId → summary name
    - `layout` (ViewLayoutInput, optional)
      - `rowHeight` (string, optional): table One of: `short`, `medium`, `tall`, `extra`.
      - `wrapCells` (boolean, optional): table
      - `cardSize` (integer, optional): board, gallery: px (50–1000)
      - `cover` (object, optional, nullable): board, gallery: the card image
      - `coverFit` (string, optional): One of: `cover`, `contain`.
      - `coverAspectRatio` (number, optional): (0.1–10)
      - `markers` (string, optional): list One of: `bullet`, `number`, `none`.
      - `calendarPropertyId` (ULID, optional): calendar: the date property placing rows
      - `calendarMode` (string, optional): One of: `month`, `week`.
      - `showWeekends` (boolean, optional)
      - `colorColumns` (boolean, optional): board
    - `extra` (object, optional)
- `window` (object, optional): Default: `{"offset":0,"limit":100}`.
  - `offset` (integer, optional): Default: `0`.
  - `limit` (integer, optional): Default: `100`. (0–1000)
  - `group` (string, optional, nullable)
  - `subGroup` (string, optional, nullable)
  - `range` (object, optional)
    - `propertyId` (ULID, optional): Default: the view's calendar property.
    - `start` (string, required): Inclusive, YYYY-MM-DD
    - `end` (string, required): Exclusive, YYYY-MM-DD
- `today` (string, optional): The caller's local date for relative date filters. Default: the server's.

## Response

- `total` (integer, required)
- `offset` (integer, required)
- `rows` (ViewRow[], required)
  - `id` (ULID, required)
  - `title` (string, required)
  - `sortKey` (string, required): (1–256 chars)
  - `properties` (object, required)
  - `createdAt` (timestamp, required)
  - `updatedAt` (timestamp, required)
  - `createdBy` (string, required, nullable): (≥ 1 chars)
  - `updatedBy` (string, required, nullable): (≥ 1 chars)
  - `group` (string, required, nullable): The row's group (null: no value or not grouped).
  - `subGroup` (string, required, nullable)
  - `computed` (object, required)
- `groups` (ViewGroup[], required)
  - `key` (string, required, nullable)
  - `subKey` (string, required, nullable): Set for sub-groups (board swimlanes); null otherwise.
  - `count` (integer, required)
  - `start` (integer, required)

```json
{
  "total": 0,
  "offset": 0,
  "rows": [
    {
      "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
      "title": "Meeting notes",
      "sortKey": "a0",
      "properties": {},
      "createdAt": "2026-11-12T09:30:00.000Z",
      "updatedAt": "2026-11-12T09:30:00.000Z",
      "createdBy": null,
      "updatedBy": null,
      "group": null,
      "subGroup": null,
      "computed": {}
    }
  ],
  "groups": [
    {
      "key": null,
      "subKey": null,
      "count": 0,
      "start": 0
    }
  ]
}
```

Errors use the envelope described at https://developers.lydie.co/errors.md.