Filtering

Pass a filter object to listRecords and paginateRecords. Every condition must match (AND), across fields and within one field.

const { data } = await sdk.listRecords('patients', {
  filter: {
    status: { in: ['active', 'pending'] },
    age: { gte: 18, lt: 65 },
  },
});

The SDK sends the filter as the JSON filter query parameter of the Data API list endpoint; the same syntax works over HTTP.

Syntax

Each key is a field key; each value is one of:

Form	Example	Meaning
Value	`{ status: 'open' }`	Equal to the value
`null`	`{ assignee: null }`	The field is unset or null
Operator map	`{ age: { gte: 18, lt: 65 } }`	Every operator must hold
Explicit operator	`{ age: { op: 'gte', value: 18 } }`	One operator, spelled out — equivalent to `{ age: { gte: 18 } }`

created_at and updated_at can also be filtered with gt, gte, lt, and lte against an RFC 3339 timestamp with an explicit offset (Z or ±HH:MM) — use them for incremental sync:

{ updated_at: { gt: lastSyncedAt } } // e.g. '2026-10-01T00:00:00Z'

Operators

Operator	Description
`eq`	Equal to `value`.
`neq`	Not equal to `value`; records where the field is unset also match.
`gt`	Greater than `value`.
`gte`	Greater than or equal to `value`.
`lt`	Less than `value`.
`lte`	Less than or equal to `value`.
`in`	Equal to any of `value`, a list of 1–100 values.
`contains`	Contains `value` as a substring, case-insensitive.
`starts_with`	Starts with `value`, case-insensitive.
`is_null`	`value: true` matches unset or null fields; `value: false` matches set ones.

Field type	Operators
`text`	`eq`, `neq`, `in`, `contains`, `starts_with`, `is_null`
`multiline`	`eq`, `neq`, `in`, `contains`, `starts_with`, `is_null`
`number`	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `is_null`
`boolean`	`eq`, `neq`, `is_null`
`date`	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `is_null`
`enum`	`eq`, `neq`, `in`, `is_null`
`reference`	`eq`, `neq`, `in`, `is_null`
`currency`	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `is_null`
`phone`	`eq`, `neq`, `in`, `contains`, `starts_with`, `is_null`
`email`	`eq`, `neq`, `in`, `contains`, `starts_with`, `is_null`
`json`	`is_null`

Values are compared as the field’s type: a number or currency field compares numerically (9 < 41), a date field compares YYYY-MM-DD dates, and text comparisons are exact except for contains and starts_with, which ignore case. % and _ in a contains/starts_with value match themselves, not wildcards.

Invalid filters are rejected, never ignored

A filter that cannot be applied exactly as written fails with 422 VALIDATION_FAILED and names the condition in error.param and error.details (for example filter.age). That covers:

a key that is not a declared field of the entity,
an operator the field’s type does not support (gt on a boolean),
a value of the wrong type ({ age: { gt: 'forty' } }), an empty or oversized in list,
malformed JSON, or a filter over 8 KB.

A silently dropped condition would return more records than you asked for. On a surface that can hold PHI, that is a disclosure, so the API refuses instead.

Limits

Limit	Value
Filter size	8 KB of JSON
Conditions per request	20
Values in one `in` list	100

Performance

Filters and sorts on a field declared indexed: true are served by a database index; others scan the entity’s records. Index the fields your app filters or sorts on routinely. See Indexing fields.

OR logic

Conditions are always ANDed. For “status is open OR assignee is me”, make two requests and merge the results, de-duplicating by id. For several values of one field, use in instead.

AI Studio

Platform

AI API

Data API

App Builder SDK

Syntax

Operators

Invalid filters are rejected, never ignored

Limits

Performance

OR logic

​Syntax

​Operators

​Invalid filters are rejected, never ignored

​Limits

​Performance

​OR logic

Syntax

Operators

Invalid filters are rejected, never ignored

Limits

Performance

OR logic