Most “list” endpoints in the Bluerails API (like listing accounts, payments, or payouts) return results in chunks, or “pages,” rather than all at once. This prevents overly large responses and allows you to fetch data incrementally. We use cursor-based pagination.

​
How Cursor Pagination Works

Instead of traditional page numbers, cursor pagination uses an opaque cursor string that points to a specific item in the dataset. To get the next page of results, you provide the cursor received from the previous response.

Query Parameters:

You control pagination using these query parameters on list endpoints:

  • limit (optional, integer):
  • Specifies the maximum number of items to return per page.
  • Default: 25
  • Maximum: 100
  • cursor (optional, string):
  • The cursor string obtained from the next_cursor field of the previous page’s response.
  • Omit this parameter entirely for the very first request to get the beginning of the list.

Response Body:

Paginated list endpoints return a JSON object with the following structure:

{
  "data": [
  // ... array of resource objects (e.g., Accounts, Payments)
  ],
  "page_size": 25, // The actual number of items returned in this response
  "next_cursor": "aBcDeFgHiJkLmNoPqRsT..." // Cursor for the next page, or null/omitted if none
}

​
Example Workflow: Listing Accounts

Initial Request(No cursor, limit=50)
Server Response(Data + next_cursor="abc")
Next Request(cursor="abc", limit=50)
Server Response(Data + next_cursor="xyz")
Repeat using latest next_cursor...
Final Response(Data + next_cursor=null)
End of List

  1. Initial Request (Get the first page)

    • Omit the cursor parameter.
    • (See diagram: “Initial Request”)

  2. Server Response (First Page)

    • The server returns the first 50 accounts and a next_cursor.
    • (See diagram: “Server Response (Data + next_cursor=“abc”)”)

  3. Next Request (Get the second page)

    • Use the next_cursor value from the previous response as the cursor query parameter.
    • (See diagram: “Next Request (cursor=“abc”, limit=50)”)

  4. Server Response (Second Page)

    • The server returns the next 50 accounts and a new next_cursor.
    • (See diagram: “Server Response (Data + next_cursor=“xyz”)”)

  5. Repeat

    • Continue making requests, using the latest next_cursor value each time.
    • (See diagram: “Repeat using latest next_cursor…”)

  6. Final Page

    • Eventually, a response will have next_cursor as null or omitted, indicating there are no more pages.
    • (See diagram: “Final Response (Data + next_cursor=null)”)