> ## Documentation Index
> Fetch the complete documentation index at: https://zite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Records
> Retrieves records from a table with filtering, sorting, and pagination using either table ID or table name.
Fetches records from a table with advanced filtering, sorting, and pagination options using either the table ID or table name.
## Pagination
| Parameter | Type | Default | Max |
| --------- | ------ | ------- | ---- |
| `limit` | number | 500 | 2000 |
| `offset` | number | 0 | - |
Use `hasMore` to determine if additional pages exist. Increment `offset` by `limit` for each subsequent request.
## Sorting
When no `sort` parameter is provided, records are returned in ascending order by creation time (`createdAt ASC`).
```json theme={null}
{
"sort": [
{ "field": "name", "direction": "asc" },
{ "field": "createdAt", "direction": "desc" }
]
}
```
| Property | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------------------------------------------------- |
| `field` | string | Yes | Field name, field ID, or system field (`id`, `createdAt`, `updatedAt`) |
| `direction` | string | No | `"asc"` (default) or `"desc"` |
`fieldId` is also accepted for backward compatibility, but `field` is preferred.
## Filtering
Use the `filter` parameter to query records. Filters support nested AND/OR logic for complex queries.
```json theme={null}
{
"filter": {
"field": "Status",
"equals": "Active"
}
}
```
Use `and` or `or` to combine multiple conditions:
```json theme={null}
{
"filter": {
"and": [
{ "field": "Status", "equals": "Active" },
{ "field": "Amount", "greater_than": 100 }
]
}
}
```
```json theme={null}
{
"filter": {
"or": [
{ "field": "Status", "equals": "Urgent" },
{ "field": "Priority", "equals": "High" }
]
}
}
```
Filters can be nested for complex logic:
```json theme={null}
{
"filter": {
"or": [
{ "field": "Status", "equals": "Urgent" },
{
"and": [
{ "field": "Priority", "equals": "High" },
{ "field": "Completed", "equals": false }
]
}
]
}
}
```
| Operator | Description | Example Value |
| -------------------------- | ----------------------------------------------------- | ------------------------- |
| `equals` | Exact match | `"Active"` |
| `does_not_equal` | Not equal to | `"Archived"` |
| `contains` | Contains substring (text) or has value (multi-select) | `"john"` |
| `does_not_contain` | Does not contain | `"test"` |
| `starts_with` | Starts with string | `"Mr."` |
| `ends_with` | Ends with string | `"@gmail.com"` |
| `is_empty` | Field has no value | `true` |
| `is_not_empty` | Field has a value | `true` |
| `in` | Value is in array | `["Active", "Pending"]` |
| `not_in` | Value is not in array | `["Archived", "Deleted"]` |
| `greater_than` | Greater than (numbers/dates) | `100` or `"2024-01-01"` |
| `greater_than_or_equal_to` | Greater than or equal | `100` |
| `less_than` | Less than | `50` |
| `less_than_or_equal_to` | Less than or equal | `50` |
| Field Type | Supported Operators |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text (`single_line_text`, `long_text`, `email`, `url`, `phone_number`) | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `in`, `not_in` |
| Number (`number`, `currency`, `percent`, `rating`, `duration`) | `equals`, `does_not_equal`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `is_empty`, `is_not_empty`, `in`, `not_in` |
| Date (`date`, `datetime`) | `equals`, `does_not_equal`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` |
| Selection (`single_select`, `multiple_select`) | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `is_empty`, `is_not_empty`, `in`, `not_in` |
| Checkbox | `equals`, `does_not_equal` |
| Attachments (`attachments`) | `is_empty`, `is_not_empty` |
| Linked Record | `contains`, `does_not_contain`, `is_empty`, `is_not_empty`, `in`, `not_in` |
**Filter by single select:**
```json theme={null}
{ "filter": { "field": "Status", "equals": "Active" } }
```
**Filter by number range:**
```json theme={null}
{
"filter": {
"and": [
{ "field": "Price", "greater_than_or_equal_to": 10 },
{ "field": "Price", "less_than": 100 }
]
}
}
```
**Filter by date:**
```json theme={null}
{ "filter": { "field": "CreatedAt", "greater_than": "2024-01-01" } }
```
**Filter by multiple values:**
```json theme={null}
{ "filter": { "field": "Status", "in": ["Active", "Pending", "Review"] } }
```
**Filter for empty/non-empty:**
```json theme={null}
{ "filter": { "field": "AssignedTo", "is_not_empty": true } }
```
## OpenAPI
````yaml help/database/openapi.json POST /bases/{databaseId}/tables/{tableId}/records/list
openapi: 3.0.1
info:
title: Zite DB REST API
description: >-
A REST API for managing Zite databases, tables, fields, and records. Build
database-driven applications with programmatic access to your structured
data.
## What is REST API
A **REST API** simplifies interaction with your database data, allowing for
automation and integration. Following RESTful principles, it seamlessly
connects to retrieve, create, and modify database data.
## Getting Started
### Authentication
All API requests require authentication using your Zite API key in the
Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```
### Base URL
https://tables.zite.com/api/v1
### Rate Limits
API requests are rate limited to ensure service quality. Standard rate
limits apply to all endpoints.
### Error Handling
The API returns standard HTTP status codes and JSON error responses with
detailed error messages.
version: 1.0.0
servers:
- url: https://tables.zite.com/api/v1
description: Zite DB API
security:
- bearerAuth: []
tags:
- name: Databases
description: Operations for managing databases
- name: Tables
description: Operations for managing tables within databases
- name: Fields
description: Operations for managing fields within tables
- name: Records
description: Operations for managing records within tables
- name: Webhooks
description: >-
Operations for managing webhook subscriptions to receive real-time
notifications when database events occur
paths:
/bases/{databaseId}/tables/{tableId}/records/list:
post:
tags:
- Records
summary: List records
description: Retrieves records from a table with filtering, sorting, and pagination
operationId: listRecords
parameters:
- name: databaseId
in: path
required: true
schema:
type: string
description: The unique identifier of the database
- name: tableId
in: path
required: true
schema:
type: string
description: >-
The unique identifier of the table. You can also use the table name
instead of the ID.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecordsRequest'
responses:
'200':
description: List of records
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecordsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
ListRecordsRequest:
type: object
properties:
limit:
type: integer
minimum: 1
maximum: 2000
default: 500
description: 'Number of records to return (default: 500, max: 2000)'
offset:
type: integer
minimum: 0
default: 0
description: Integer-based offset - Number of records to skip for pagination
sort:
type: array
items:
$ref: '#/components/schemas/SortObject'
description: >-
Array of sort objects. When not provided, records are returned in
ascending order by creation time (createdAt ASC). All queries
include an internal tie-breaker to ensure deterministic ordering
across paginated requests.
filter:
type: object
additionalProperties: true
description: >-
Filter condition to query records. Supports nested AND/OR logic.
Each condition requires `field` (field ID or name) and one operator
(`equals`, `does_not_equal`, `contains`, `greater_than`, `in`,
etc.). See [Filtering
documentation](/help/database/api/list-records#filtering) for
details.
example:
field: Status
equals: Active
example:
sort:
- field: name
direction: asc
- field: createdAt
direction: desc
filter:
and:
- field: Status
equals: Active
- field: Amount
greater_than: 100
limit: 100
offset: 0
ListRecordsResponse:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/Record'
description: Array of records
total:
type: integer
description: Total number of records matching the query
hasMore:
type: boolean
description: Whether there are more records available beyond this page
required:
- records
- total
- hasMore
example:
records:
- id: d4b3c2a3-c46b-46a1-a8ec-81b664bb41cb
data:
f6JE46z2WoX: ''
f5gMv8mk8CX: ''
foEBBtqDY1F: false
fields:
Name: ''
Notes: ''
Active: false
createdAt: '2025-11-13T11:59:45.000Z'
updatedAt: '2025-11-13T11:59:45.000Z'
total: 1250
hasMore: true
SortObject:
type: object
properties:
field:
type: string
description: >-
Field name, field ID, or system field name (id, createdAt,
updatedAt)
fieldId:
type: string
description: Deprecated. Use 'field' instead. Kept for backward compatibility.
deprecated: true
direction:
type: string
enum:
- asc
- desc
default: asc
description: 'Sort direction (default: asc)'
anyOf:
- required:
- field
- required:
- fieldId
Record:
type: object
properties:
id:
type: string
format: uuid
description: Unique UUID identifier for the record
data:
type: object
additionalProperties: true
description: Record data with field IDs as keys
example:
fwtJyga6dso: John Doe
k8mNp2xQ9rL: john.doe@newcompany.com
vB3zXc7Hf2w: low
fields:
type: object
additionalProperties: true
description: Record data with field names as keys
example:
Name: John Doe
Email: john.doe@newcompany.com
Priority: low
createdAt:
type: string
format: date-time
description: ISO timestamp of when the record was created
updatedAt:
type: string
format: date-time
description: ISO timestamp of when the record was last updated
required:
- id
- data
- fields
- createdAt
- updatedAt
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Error code
message:
type: string
description: Human-readable error message
required:
- code
- message
required:
- error
responses:
BadRequest:
description: Invalid request data or validation failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidRecordId:
value:
error:
code: INVALID_RECORD_ID
message: Record ID is not in valid UUID format
validationError:
value:
error:
code: BAD_REQUEST
message: Invalid request data or validation failure
Unauthorized:
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: UNAUTHORIZED
message: Invalid or missing API key
NotFound:
description: Requested resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: NOT_FOUND
message: Requested resource does not exist
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Enter your Zite API key. Format: Bearer '
````