---
title: Using the API
description: Pagination, filtering, sorting and selecting fields when you read records.
sidebar:
  order: 7
---
For full detailed information on how to the use the API and test your queries, you can use the [following webpage](/api/explorer). You can paste your API key and click on “Show my tables” button on the top to see the list of tables and how to query the data from those tables.

## Pagination

List endpoints return results in pages. Each response includes `has_more` and `next_cursor`. To get the next page, send `next_cursor` back as `cursor` (a query parameter on `GET /v1/{org_id}/tables`, a JSON body field on a records query) and repeat until `has_more` is `false`. A cursor only works with the same table, filter and sort it came from; anything else returns `invalid_cursor`.

- `limit`: results per page, 1 to 1000. Default 100.
- `cursor`: the `next_cursor` value from the previous page.

## Filtering, sorting and selecting fields

Query records with `POST /v1/{org_id}/tables/{table}/records/query`. Every part of the JSON body is optional:

```json
{
  "filter": {
    "and": [
      { "field": "status", "op": "in", "value": ["open", "partial"] },
      { "field": "order_date", "op": "gte", "value": "2026-10-01" }
    ]
  },
  "sort": [{ "field": "order_date", "direction": "desc" }],
  "fields": ["po_number", "status", "total"],
  "limit": 100
}
```

| Operator | Matches |
| --- | --- |
| eq, ne | Equal or not equal to the value |
| gt, gte, lt, lte | Greater or less than (or equal to) the value |
| in | Any of the values (an array of at most 100) |
| contains, starts\_with | Contains or starts with the text, ignoring case |
| is\_null | Empty when the value is true, not empty when false |

Combine conditions with `and` or `or` groups, nested up to 3 deep with at most 50 conditions in total. Not every field can be filtered or sorted: `GET /v1/{org_id}/tables/{table}` shows each field's `filterable`, `sortable` and `filter_operators`.

`sort` takes up to three `{ field, direction }` keys, where `direction` is `asc` (the default) or `desc`. Without a sort, records come back by `created_at`, oldest first.

`fields` limits which fields come back, which makes responses smaller and faster. Every record always includes `id`, `created_at` and `updated_at` (plus `parent_record_id` on subtables), and the requested fields are inside its `fields` object.
