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.

  • Verified Nov 17, 2026
  • Classic builder

On this page
  1. Sort by one field
  2. Sort by several fields
  3. Page through records
  4. Fetch every page

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):

Shell
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 #

ParameterWhat it does
pageThe page to return, starting at 1.
limitRecords 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
}
FieldMeaning
total_itemsHow many records match the request's filters.
total_pagestotal_items divided by limit, rounded up.
current_pageThe page in this response.
limitThe 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:

JavaScript
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 explains the limits and the headers that show how many requests you have left.

Was this page helpful?

Something wrong or missing on this page? Tell us.