> ## Documentation Index > Fetch the complete documentation index at: https://help.teable.ai/llms.txt > Use this file to discover all available pages before exploring further. # List records > Retrieve a list of records with support for filtering, sorting, grouping, and pagination. The response includes record data and optional group information. Required token scopes: `record|read` ## OpenAPI ````yaml /swagger.json get /table/{tableId}/record openapi: 3.0.0 info: version: 1.0.0 title: Teable App description: Manage Data as easy as drink a cup of tea x-logo: backgroundColor: '#F0F0F0' altText: Teable logo servers: - url: https://app.teable.ai/api security: [] tags: - name: base x-group: project - name: base node x-group: project node - name: base-share x-group: project-share paths: /table/{tableId}/record: get: tags: - record summary: List records description: >- Retrieve a list of records with support for filtering, sorting, grouping, and pagination. The response includes record data and optional group information. Required token scopes: `record|read` parameters: - schema: type: string required: true name: tableId in: path - schema: type: array items: type: string description: >- 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 required: false description: >- 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 name: projection in: query - schema: type: string enum: - json - text default: json description: >- Define the return value formate, you can set it to text if you only need simple string value required: false description: >- Define the return value formate, you can set it to text if you only need simple string value name: cellFormat in: query - schema: type: string enum: - id - name - dbFieldName default: name description: >- 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 required: false description: >- 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 name: fieldKeyType in: query - schema: type: string example: viwXXXXXXX description: >- Set the view you want to fetch. When provided, records will follow that view's filter and sort settings. When omitted, the API queries the table without applying a view. required: false description: >- Set the view you want to fetch. When provided, records will follow that view's filter and sort settings. When omitted, the API queries the table without applying a view. name: viewId in: query - schema: anyOf: - type: string - type: boolean description: >- When a viewId is specified, configure this to true will ignore the view's filter, sort, etc required: false description: >- When a viewId is specified, configure this to true will ignore the view's filter, sort, etc name: ignoreViewQuery in: query - schema: type: string example: '{field} = ''Completed'' AND {field} > 5' deprecated: true required: false name: filterByTql in: query - schema: type: string description: >- 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. required: false description: >- 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. name: filter in: query - schema: anyOf: - type: array items: type: string minItems: 1 maxItems: 1 - type: array items: type: string minItems: 2 maxItems: 2 - type: array items: anyOf: - type: string - anyOf: - type: string - type: boolean minItems: 3 maxItems: 3 default: - searchValue - fieldIdOrName - false description: Search for records that match the specified field and value required: false description: Search for records that match the specified field and value name: search in: query - schema: anyOf: - type: array items: type: string minItems: 2 maxItems: 2 - type: string example: - fldXXXXXXX - recXXXXXXX description: >- 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. required: false description: >- 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. name: filterLinkCellCandidate in: query - schema: anyOf: - type: array items: type: string minItems: 2 maxItems: 2 - type: string example: - fldXXXXXXX - recXXXXXXX description: >- 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 required: false description: >- 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 name: filterLinkCellSelected in: query - schema: type: array items: type: string description: Filter selected records by record ids required: false description: Filter selected records by record ids name: selectedRecordIds in: query - schema: type: string description: >- An array of sort objects that specifies how the records should be ordered. required: false description: >- An array of sort objects that specifies how the records should be ordered. name: orderBy in: query - schema: type: string description: >- An array of group objects that specifies how the records should be grouped. required: false description: >- An array of group objects that specifies how the records should be grouped. name: groupBy in: query - schema: type: string description: An array of group ids that specifies which groups are collapsed required: false description: An array of group ids that specifies which groups are collapsed name: collapsedGroupIds in: query - schema: type: string example: qry_xxxxxxxx description: >- When provided, other query parameters will be merged with the saved ones. required: false description: >- When provided, other query parameters will be merged with the saved ones. name: queryId in: query - schema: anyOf: - type: string - type: boolean description: >- Whether to include query extra metadata such as group points and search hit indexes. Group metadata defaults to enabled; optimized generated-index searches require explicit opt-in for search hit indexes. required: false description: >- Whether to include query extra metadata such as group points and search hit indexes. Group metadata defaults to enabled; optimized generated-index searches require explicit opt-in for search hit indexes. name: includeQueryExtra in: query - schema: anyOf: - type: string - type: number default: 100 example: 100 description: The record count you want to take, maximum is 1000 required: false description: The record count you want to take, maximum is 1000 name: take in: query - schema: anyOf: - type: string - type: number default: 0 example: 0 description: The records count you want to skip required: false description: The records count you want to skip name: skip in: query - schema: type: string minLength: 1 description: >- Opaque keyset cursor for the next page. Use the nextCursor returned by the previous page; it encodes the last row position for the current order. Cannot be combined with skip > 0. required: false description: >- Opaque keyset cursor for the next page. Use the nextCursor returned by the previous page; it encodes the last row position for the current order. Cannot be combined with skip > 0. name: cursor in: query responses: '200': description: List of records content: application/json: schema: type: object properties: records: type: array items: type: object properties: id: type: string description: The record id. name: type: string description: primary field value fields: type: object additionalProperties: nullable: true description: >- Objects with a fields key mapping fieldId or field name to value for that field. autoNumber: type: number description: Auto number, a unique identifier for each record createdTime: type: string description: >- Created time, date ISO string (new Date().toISOString). lastModifiedTime: type: string description: >- Last modified time, date ISO string (new Date().toISOString). createdBy: type: string description: Created by, user name lastModifiedBy: type: string description: Last modified by, user name permissions: type: object additionalProperties: type: object additionalProperties: type: boolean description: Permissions for the record undeletable: type: boolean description: Whether the record is undeletable required: - id - fields example: - id: recXXXXXXX fields: single line text: text value description: 'Array of record objects ' extra: type: object properties: groupPoints: type: array nullable: true items: anyOf: - type: object properties: id: type: string type: type: number enum: - 0 depth: type: number maximum: 2 minimum: 0 value: nullable: true isCollapsed: type: boolean required: - id - type - depth - isCollapsed - type: object properties: type: type: number enum: - 1 count: type: number required: - type - count description: Group points for the view allGroupHeaderRefs: type: array items: type: object properties: id: type: string depth: type: number maximum: 2 minimum: 0 required: - id - depth description: >- All group header refs for the view, including collapsed group headers searchHitIndex: type: array nullable: true items: type: object properties: recordId: type: string fieldId: type: string required: - recordId - fieldId description: >- The index of the records that match the search, highlight the records nextCursor: type: string minLength: 1 description: >- Keyset cursor for fetching the next page without OFFSET required: - records security: - bearerAuth: [] x-codeSamples: - lang: Shell source: |- curl --request GET \ --url 'https://app.teable.ai/api/table/%7BtableId%7D/record?projection=SOME_ARRAY_VALUE&cellFormat=SOME_STRING_VALUE&fieldKeyType=SOME_STRING_VALUE&viewId=viwXXXXXXX&ignoreViewQuery=SOME_STRING_VALUE&filterByTql=%7Bfield%7D+%3D+%27Completed%27+AND+%7Bfield%7D+%3E+5&filter=SOME_STRING_VALUE&search=SOME_ARRAY_VALUE&filterLinkCellCandidate=fldXXXXXXX&filterLinkCellCandidate=recXXXXXXX&filterLinkCellSelected=fldXXXXXXX&filterLinkCellSelected=recXXXXXXX&selectedRecordIds=SOME_ARRAY_VALUE&orderBy=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&collapsedGroupIds=SOME_STRING_VALUE&queryId=qry_xxxxxxxx&includeQueryExtra=SOME_STRING_VALUE&take=100&skip=0&cursor=SOME_STRING_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' - lang: JavaScript source: >- const url = 'https://app.teable.ai/api/table/%7BtableId%7D/record?projection=SOME_ARRAY_VALUE&cellFormat=SOME_STRING_VALUE&fieldKeyType=SOME_STRING_VALUE&viewId=viwXXXXXXX&ignoreViewQuery=SOME_STRING_VALUE&filterByTql=%7Bfield%7D+%3D+%27Completed%27+AND+%7Bfield%7D+%3E+5&filter=SOME_STRING_VALUE&search=SOME_ARRAY_VALUE&filterLinkCellCandidate=fldXXXXXXX&filterLinkCellCandidate=recXXXXXXX&filterLinkCellSelected=fldXXXXXXX&filterLinkCellSelected=recXXXXXXX&selectedRecordIds=SOME_ARRAY_VALUE&orderBy=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&collapsedGroupIds=SOME_STRING_VALUE&queryId=qry_xxxxxxxx&includeQueryExtra=SOME_STRING_VALUE&take=100&skip=0&cursor=SOME_STRING_VALUE'; const options = {method: 'GET', headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } - lang: Node.js source: |- const http = require('https'); const options = { method: 'GET', hostname: 'app.teable.ai', port: null, path: '/api/table/%7BtableId%7D/record?projection=SOME_ARRAY_VALUE&cellFormat=SOME_STRING_VALUE&fieldKeyType=SOME_STRING_VALUE&viewId=viwXXXXXXX&ignoreViewQuery=SOME_STRING_VALUE&filterByTql=%7Bfield%7D+%3D+%27Completed%27+AND+%7Bfield%7D+%3E+5&filter=SOME_STRING_VALUE&search=SOME_ARRAY_VALUE&filterLinkCellCandidate=fldXXXXXXX&filterLinkCellCandidate=recXXXXXXX&filterLinkCellSelected=fldXXXXXXX&filterLinkCellSelected=recXXXXXXX&selectedRecordIds=SOME_ARRAY_VALUE&orderBy=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&collapsedGroupIds=SOME_STRING_VALUE&queryId=qry_xxxxxxxx&includeQueryExtra=SOME_STRING_VALUE&take=100&skip=0&cursor=SOME_STRING_VALUE', headers: { Authorization: 'Bearer REPLACE_BEARER_TOKEN' } }; const req = http.request(options, function (res) { const chunks = []; res.on('data', function (chunk) { chunks.push(chunk); }); res.on('end', function () { const body = Buffer.concat(chunks); console.log(body.toString()); }); }); req.end(); - lang: Python source: >- import http.client conn = http.client.HTTPSConnection("app.teable.ai") headers = { 'Authorization': "Bearer REPLACE_BEARER_TOKEN" } conn.request("GET", "/api/table/%7BtableId%7D/record?projection=SOME_ARRAY_VALUE&cellFormat=SOME_STRING_VALUE&fieldKeyType=SOME_STRING_VALUE&viewId=viwXXXXXXX&ignoreViewQuery=SOME_STRING_VALUE&filterByTql=%7Bfield%7D+%3D+%27Completed%27+AND+%7Bfield%7D+%3E+5&filter=SOME_STRING_VALUE&search=SOME_ARRAY_VALUE&filterLinkCellCandidate=fldXXXXXXX&filterLinkCellCandidate=recXXXXXXX&filterLinkCellSelected=fldXXXXXXX&filterLinkCellSelected=recXXXXXXX&selectedRecordIds=SOME_ARRAY_VALUE&orderBy=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&collapsedGroupIds=SOME_STRING_VALUE&queryId=qry_xxxxxxxx&includeQueryExtra=SOME_STRING_VALUE&take=100&skip=0&cursor=SOME_STRING_VALUE", headers=headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) components: securitySchemes: bearerAuth: type: http scheme: bearer ````