Pagination

In this guide, we will look at how to work with paginated responses when querying the Slateo API. By default, all responses limit results to twenty. However, you can go as high as 100 by adding a limit parameter to your requests.

Overview

When an API response returns a list of objects, no matter the amount, pagination is supported. In paginated responses, objects are nested in an items array and have a nextCursor attribute for continuing to the next page. You can use the cursor query parameter to navigate through pages.

Usage

Using cursors for pagination

In this example, we request the page using a cursor to get the next set of queries. As a result, we get a list of queries and can use the nextCursor to fetch the next page.

Name
cursor
Type
string
Description
The cursor for pagination to get the next set of results.
Name
limit
Type
integer
Description
Limit the number of items returned (max 100, default 20).

Manual pagination using cURL

curl -G https://api.slateo.ai/api/queries \
  -H "Authorization: Bearer {token}" \
  -d cursor="eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9" \
  -d limit=10

Paginated response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "sql": "SELECT * FROM orders WHERE created_at > '2024-01-01'",
      // ...
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "sql": "SELECT COUNT(*) FROM users",
      // ...
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "sql": "SELECT * FROM products WHERE status = 'active'",
      // ...
    }
  ],
  "nextCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMyJ9"
}

Iterating through all pages

To fetch all results, continue making requests with the nextCursor until the response no longer includes a nextCursor field.

let allItems = [];
let cursor = null;

do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.append('cursor', cursor);
  
  const response = await fetch(`https://api.slateo.ai/api/queries?${params}`, {
    headers: { 'Authorization': 'Bearer {token}' }
  });
  
  const data = await response.json();
  allItems = allItems.concat(data.items);
  cursor = data.nextCursor;
} while (cursor);

FAQ

What is the maximum page size?

The maximum page size is 100 items per request. The default is 20 items if no limit parameter is specified.

How long are cursors valid?

Cursors are valid for 24 hours after they are generated. After that, you'll need to start a new pagination sequence from the beginning.

Can I use offset-based pagination instead of cursors?

No, the Slateo API uses cursor-based pagination exclusively. Cursor-based pagination is more efficient and provides consistent results even when the underlying data changes between requests.

What happens if the data changes while I'm paginating?

Cursor-based pagination provides a consistent snapshot of the data at the time you started paginating. New items added after you start won't appear in your results, and deleted items will still be included if they existed when you started.