---
title: "List records"
method: GET
path: "/table/{tableId}/record"
tags: ["record"]
---

# List records

`GET /table/{tableId}/record`

Retrieve a list of records with support for filtering, sorting, grouping, and pagination. The response includes record data and optional group information.

## Path parameters

- `tableId` string, required

## Query parameters

- `projection` string[] — If you want to get only some fields, pass in this parameter, otherwise all visible fields will be obtained, The parameter value depends on the specified fieldKeyType to determine whether it is name or id
- `cellFormat` 'json' | 'text' — Define the return value formate, you can set it to text if you only need simple string value
- `fieldKeyType` 'id' | 'name' | 'dbFieldName' — Define the key type of record.fields[key], You can click "systemInfo" in the field edit box to get fieldId or enter the table design screen with all the field details
- `viewId` string — Set the view you want to fetch, default is first view. result will filter and sort by view options.
- `ignoreViewQuery` union — When a viewId is specified, configure this to true will ignore the view's filter, sort, etc
  - string
  - boolean
- `filterByTql` string
- `filter` string — A filter object for complex query conditions based on fields, operators, and values. Use our visual query builder at https://app.teable.ai/developer/tool/query-builder to build filters.
- `search` union — Search for records that match the specified field and value
  - string[]
  - string[]
  - union[]
    - union
      - string
      - string
      - boolean
- `filterLinkCellCandidate` union — Filter out the records that can be selected by a given link cell from the relational table. For example, if the specified field is one to many or one to one relationship, recordId for which the field has already been selected will not appear.
  - string[]
  - string
- `filterLinkCellSelected` union — Filter out selected records based on this link cell from the relational table. Note that viewId, filter, and orderBy will not take effect in this case because selected records has it own order. Ignoring recordId gets all the selected records for the field
  - string[]
  - string
- `selectedRecordIds` string[] — Filter selected records by record ids
- `orderBy` string — An array of sort objects that specifies how the records should be ordered.
- `groupBy` string — An array of group objects that specifies how the records should be grouped.
- `collapsedGroupIds` string — An array of group ids that specifies which groups are collapsed
- `queryId` string — When provided, other query parameters will be merged with the saved ones.
- `take` union — The record count you want to take, maximum is 1000
  - string
  - number
- `skip` union — The records count you want to skip
  - string
  - number

## Response `200`

List of records

- object
  - `records` object[], required — Array of record objects
    - `id` string, required — The record id.
    - `name` string — primary field value
    - `fields` object, required — Objects with a fields key mapping fieldId or field name to value for that field.
    - `autoNumber` number — Auto number, a unique identifier for each record
    - `createdTime` string — Created time, date ISO string (new Date().toISOString).
    - `lastModifiedTime` string — Last modified time, date ISO string (new Date().toISOString).
    - `createdBy` string — Created by, user name
    - `lastModifiedBy` string — Last modified by, user name
    - `permissions` object — Permissions for the record
    - `undeletable` boolean — Whether the record is undeletable
  - `extra` object
    - `groupPoints` union[], nullable — Group points for the view
      - union
        - object
          - `id` string, required
          - `type` 0, required
          - `depth` number, required
          - `value` unknown
          - `isCollapsed` boolean, required
        - object
          - `type` 1, required
          - `count` number, required
    - `allGroupHeaderRefs` object[] — All group header refs for the view, including collapsed group headers
      - `id` string, required
      - `depth` number, required
    - `searchHitIndex` object[], nullable — The index of the records that match the search, highlight the records
      - `recordId` string, required
      - `fieldId` string, required

---

[API](https://skmtc.net/teable/apis/teable-app.md) · [All operations](https://skmtc.net/teable/apis/teable-app/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/teable/teable-app/versions/7515f3b33d79/schema)