---
title: "List records"
method: GET
path: "/api/v1/records"
tags: ["Records"]
---

# List records

`GET /api/v1/records`

## Request

- Base URL: `https://api-docs.busabase.com`
- URL: `https://api-docs.busabase.com/api/v1/records`
- Auth: none declared

## Query parameters

- `limit` integer: Records per page. Capped at 100; ask for the next page with `cursor`.
- `baseId` string: Restrict to one Base. OMITTING it lists records across the WHOLE SPACE, which is rarely what a caller means and is easy to miss — every other parameter still applies, so an unscoped query looks like it worked.
- `cursor` string: Opaque page cursor: pass back the `nextCursor` from the previous response. Do not construct or parse it — it is keyed on `createdAt`, or on the sort field when `sort` is given, and that is an implementation detail.
- `status` 'active' | 'archived': `active` is the live table; `archived` is the Base's trash.
- `summary` union: Return compact list previews: field values larger than 4 KB are replaced with omission markers, and Base field definitions and computed lookup values are omitted. Omit for full records; use records.get to read the complete content of a selected row.
  - boolean
  - unknown
  - unknown
- `filters` object[]: View filters — a best-effort SUPERSET, not an exact answer. They mean what the grid means (a currency number reads as "$1,234.00", a select as its choice label), and the server may return records that do not match, so the caller must narrow them again and must NOT trust `limit` alongside them. Use `valueFilters` when you need an exact row set.
  - `fieldSlug` string, required
  - `fieldType` string
  - `operator` 'contains' | 'equals' | 'not_empty' | 'is_empty' | 'is_true' | 'is_false', required
  - `value` unknown
- `valueFilters` union[]: EXACT value comparisons, unlike `filters` which are a best-effort superset. The returned rows are exactly those that match, so `limit` can be trusted alongside them. Entries are ANDed; an entry may instead be `{ any: [...] }` to OR its comparisons, which makes the list a CNF and can express any boolean combination. Requires `baseId`. Compares number, date, checkbox and text-like fields (text and select support eq/ne only); anything else is a 400 rather than a silently dropped condition.
  - union
    - object
      - `fieldSlug` string, required
      - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte', required
      - `value` union, required
        - number
        - string
        - boolean
    - object
      - `any` object[], required
        - `fieldSlug` string, required
        - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte', required
        - `value` union, required
          - number
          - string
          - boolean
- `sort` object: Sort by one field. Only number and date fields sort authoritatively (their typed value column matches a client's own ordering); any other field type is returned in the default order and left for the caller to sort.
  - `fieldSlug` string, required
  - `fieldType` string
  - `direction` 'asc' | 'desc'

## Response `200`

A page of canonical records plus an opaque nextCursor (null at the end). `status=archived` lists the Base's trash instead of its live rows.

- object
  - `records` object[], required
    - `id` string, required
    - `baseId` string, required
    - `headCommitId` string, required
    - `parentRecordId` string, required
    - `parentCommitId` string, required
    - `status` 'active' | 'archived', required
    - `createdBy` string, required
    - `createdByUser` object
      - `id` string, required
      - `name` string, required
      - `email` string, required
      - `image` string, required
      - `role` string
    - `fieldUsers` object
    - `archivedAt` string, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `base` object, required
      - `id` string, required
      - `nodeId` string, required
      - `slug` string, required
      - `name` string, required
      - `description` string, required
      - `reviewPolicy` object, required
        - `kind` unknown, required
        - `requiredApprovals` number, required
      - `createdAt` string, required
      - `fields` object[], required
        - `id` string, required
        - `baseId` string, required
        - `slug` string, required
        - `name` union, required
          - string
          - object
        - `type` 'text' | 'longtext' | 'markdown' | 'html' | 'attachment' | 'relation' | 'member' | 'number' | 'date' | 'checkbox' | 'select' | 'multiselect' | 'url' | 'embed' | 'email' | 'phone' | 'created_time' | 'updated_time' | 'created_by' | 'updated_by' | 'auto_number' | 'ai_summary' | 'ai_tags' | 'code' | 'json' | 'yaml' | 'formula' | 'lookup' | 'whiteboard', required
        - `required` boolean, required
        - `position` number, required
        - `options` object
          - `help` object
            - `description` string
            - `example` string
          - `ai` object
            - `model` string
            - `prompt` string
            - `reviewRequired` boolean
            - `sourceFieldIds` string[]
          - `attachment` object
            - `allowedMimeTypes` string[]
          - `choices` object[]
            - `color` string
            - `id` string, required
            - `name` string, required
          - `code` object
            - `language` string
          - `date` object
            - `includeTime` boolean
            - `timezone` string: IANA time zone, e.g. "Asia/Shanghai". Omit to show each reader their own local time.
          - `embed` object
            - `aspectRatio` '16:9' | '4:3' | '1:1'
            - `providers` string[]
          - `formula` object
            - `expression` string, required
            - `format` 'auto' | 'number' | 'currency' | 'percent' | 'date'
            - `precision` integer
            - `currency` string
          - `inverseFieldId` string
          - `lookup` object
            - `relationFieldSlug` string, required: Slug of a `relation` field on THIS Base — the hop to follow.
            - `targetFieldSlug` string, required: Slug of the field on the related Base whose values are pulled over.
            - `rollup` 'values' | 'count' | 'sum' | 'average' | 'min' | 'max' | 'concatenate'
            - `limit` 'all' | 'first': `first` looks at only the first linked record; default `all`.
          - `multiple` boolean
          - `number` object
            - `format` 'plain' | 'currency'
            - `currency` string
            - `locale` string
          - `targetBaseId` string: Relation target Base id (bse_…). Or pass targetBaseSlug to name it by slug.
          - `targetBaseSlug` string: Relation target Base by slug — a convenience alias for targetBaseId, resolved server-side (active bases in the current space). If both are given, targetBaseId wins.
    - `headCommit` object, required
      - `id` string, required
      - `baseId` string, required
      - `targetType` 'base' | 'node', required
      - `nodeId` string, required
      - `operationId` string, required
      - `parentCommitId` string, required
      - `payload` object, required
      - `operation` 'node_create' | 'node_rename' | 'node_delete' | 'node_restore' | 'node_move' | 'record_create' | 'record_update' | 'record_delete' | 'record_variant' | 'view_create' | 'view_update' | 'view_delete' | 'view_restore' | 'base_add_field' | 'base_delete_field' | 'base_update_field' | 'base_convert_field' | 'base_reorder_fields' | 'base_restore_field' | 'base_archive' | 'base_restore' | 'record_restore' | 'skill_file_create' | 'skill_file_update' | 'skill_file_delete' | 'skill_metadata_update' | 'drive_file_create' | 'drive_file_update' | 'drive_file_delete' | 'drive_metadata_update' | 'airapp_file_create' | 'airapp_file_update' | 'airapp_file_delete' | 'airapp_metadata_update' | 'doc_update' | 'whiteboard_document_update' | 'workflow_document_update' | 'html_document_update', required
      - `message` string, required
      - `author` string, required
      - `authorUser` object
        - `id` string, required
        - `name` string, required
        - `email` string, required
        - `image` string, required
        - `role` string
      - `createdAt` string, required
  - `nextCursor` string, required

---

[API](https://skmtc.dev/busabase/apis/busabase-api.md) · [All operations](https://skmtc.dev/busabase/apis/busabase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/busabase/apis/busabase-api/revisions/bc6a7d5ff4c1?raw)