Pagination

Flux API returns cursor-based pagination for both folder reads and _search queries. Each response includes absolute next and previous URLs that already contain the cursor token and any query parameters you supplied.

Overview

Cursor pagination keeps responses consistent even when new documents are published mid-request. Pass the cursor you received back to the API using either the next or previous parameter (never both).

Why cursors?

  • Consistent order – Cursors encode the document key and sort order so items are not skipped or repeated.
  • Stateless – No server session is required; each request is independent.
  • Link-friendly – Responses include fully qualified URLs, so you can follow them directly or extract the cursor parameter for custom clients.

Pagination Parameters

Query Parameters

  • Name
    limit
    Type
    integer
    Default
    default:100
    Description

    Items per page (1–100). Higher values increase response size and time. See API Limits for plan caps.

  • Name
    next
    Type
    string
    Description

    Cursor obtained from the prior response when loading the next page. Must not be combined with previous.

  • Name
    previous
    Type
    string
    Description

    Cursor obtained from the prior response when paginating backwards. Must not be combined with next.

Response Structure

  • Name
    limit
    Type
    integer
    Description

    Echoes the effective limit applied to the request.

  • Name
    next
    Type
    string | null
    Description

    Absolute URL (including the encoded cursor) for the next page. null when no more pages remain.

  • Name
    previous
    Type
    string | null
    Description

    Absolute URL for the previous page. null for the first page.

  • Name
    results
    Type
    array
    Description

    Array of resources for the current page.

You can follow the next/previous URL directly with the same HTTP method and body, or parse the cursor value from the URL and add it to your own request builder.

Basic Pagination

First Page Request

Start with the base endpoint and a limit. No cursor is needed.

Request

curl -X POST "https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=10" \
  -H "Authorization: Secure <access_key>:<signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "$": {
        "all_of": [
          {"status__eq": "published"}
        ]
      }
    }
  }'

Response

{
  "limit": 10,
  "next": "https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=10&next=eyJjcmVh...X0MiLCJfa2V5IjoiYXJ0aWNsZV8xMCJ9",
  "previous": null,
  "results": [
    {
      "_sys": {
        "key": "dw2qC5qRwxuZ",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "folder": "aooxoscltikj"
      },
      "data": {
        "title": "Introduction to AI",
        "status": "published"
      }
    }
  ]
}

Next Page Navigation

Using the next URL

Pass the response’s next URL directly (same HTTP method, headers, and body), or extract its next query parameter if you prefer to rebuild the URL yourself.

Request

curl -X POST "https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=10&next=eyJjcmVh...xMCJ9" \
  -H "Authorization: Secure <access_key>:<signature>" \
  -H "Content-Type: application/json" \
  -d '{ ...same body as first request... }'

Second Page Response

{
  "limit": 10,
  "next": "https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=10&next=eyJjcmVh...NEJ9",
  "previous": "https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=10&previous=eyJjcmVh...QzB9",
  "results": [
    {
      "_sys": {
        "key": "article_11",
        "created_at": "2024-01-14T10:30:00Z",
        "updated_at": "2024-01-14T10:30:00Z",
        "folder": "aooxoscltikj"
      },
      "data": {
        "title": "Next Article",
        "status": "published"
      }
    }
  ]
}

Previous Page Navigation

Walking Backwards

Use the previous URL from a later response to move back one page. This is helpful when supporting “Load newer” or reverse infinite scroll experiences.

cURL

curl -X POST "https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=10&previous=eyJjcmVh...In0=" \
  -H "Authorization: Secure <access_key>:<signature>" \
  -H "Content-Type: application/json" \
  -d '{ ...same body... }'

Complete Pagination Loop

Iterate Until No Pages Remain

The following examples keep requesting pages until next returns null.

async function fetchAllArticles(searchBody) {
  const baseUrl = 'https://7c9h4pwu.fxns.io/api-prefix/articles/_search?limit=50';
  let url = baseUrl;
  const allResults = [];

  while (url) {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Secure ${accessKey}:${signature}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(searchBody)
    });

    const page = await response.json();
    allResults.push(...page.results);
    url = page.next; // null when finished
  }

  return allResults;
}

Was this page helpful?