# Sort and page through records

> Sort REST API record lists by one or more fields, and read large tables page by page with page and limit, up to 100 records per request.

Source: https://tadabase.com/docs/developers/sorting-and-pagination  
Status: Verified Nov 17, 2026. Checked against the current product

`GET /data-tables/{tableId}/records` returns records one page at a time. Use `order` or `sort_by` to choose the order, and `page` and `limit` to walk through every page.

## Sort by one field

Send the field's slug in `order` and the direction in `order_by` (`asc` or `desc`; `asc` when left out):

```bash
curl -G "https://api.tadabase.io/api/v1/data-tables/{tableId}/records" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  --data-urlencode "order=field_37" \
  --data-urlencode "order_by=desc"
```

You can sort by any field slug of the table, or by `id`. A name that is neither is ignored. Without a sort, records come back in the order they were created, oldest first.

## Sort by several fields

Use `sort_by` with one entry per field, in order of priority:

```text
sort_by[0][sort]=field_38
sort_by[0][by]=asc
sort_by[1][sort]=field_37
sort_by[1][by]=desc
```

`order` takes priority: if a request sends both, only `order` is used. Records that tie on every sort field are kept in creation order.

- A connection field sorts by the display value of the connected record.
- An Equation field with a number result sorts as a number.
- A Name field sorts by title, then first, middle and last name.

## Page through records

| Parameter | What it does |
| --- | --- |
| `page` | The page to return, starting at 1. |
| `limit` | Records per page: 100 at most, and 100 when you leave it out. A larger number is treated as 100. |

Every list response tells you where you are:

```json
{
  "type": "success",
  "items": [ ... ],
  "total_items": 2350,
  "total_pages": 24,
  "current_page": 1,
  "limit": 100
}
```

| Field | Meaning |
| --- | --- |
| `total_items` | How many records match the request's filters. |
| `total_pages` | `total_items` divided by `limit`, rounded up. |
| `current_page` | The page in this response. |
| `limit` | The page size used. |

Paging is by page number. If records are added or deleted while you read, a record can move to a neighboring page; sorting by `id` keeps the order stable for records that already exist.

## Fetch every page

Each page is one request and counts toward your rate limit. This loop reads every page, asks only for the fields it needs, and waits when the API answers 429:

```js
const BASE = 'https://api.tadabase.io/api/v1';
const headers = {
  'X-Tadabase-App-id': 'YOUR_APP_ID',
  'X-Tadabase-App-Key': 'YOUR_API_KEY',
  'X-Tadabase-App-Secret': 'YOUR_API_SECRET',
};

async function fetchAllRecords(tableId) {
  const all = [];
  let page = 1;
  let totalPages = 1;
  while (page <= totalPages) {
    const q = new URLSearchParams({ page: String(page), limit: '100', order: 'id', fields: 'id,field_36,field_37' });
    const res = await fetch(`${BASE}/data-tables/${tableId}/records?${q}`, { headers });
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') || 60);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue; // try the same page again
    }
    const data = await res.json();
    if (data.type !== 'success') throw new Error(data.msg);
    all.push(...data.items);
    totalPages = data.total_pages;
    page += 1;
  }
  return all;
}
```

[API rate limits](https://tadabase.com/docs/developers/rate-limiting) explains the limits and the headers that show how many requests you have left.
