Paging Through API Responses

Learn how to page through lists and other API responses.


Finix's API supports listing resources such as Transfer and Identities. Querying through these collections of resources relies on cursor-based pagination.

When you query for a list, you provide the number of entries you want by with limit. Finix returns back a page of results per the limit you specified, as well as a next_cursor. This cursor is an opaque string that points to the end of the current page of results.

Copy
Copied
curl "https://finix.sandbox-payments-api.com/transfers?limit=10" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

The response looks like:

Copy
Copied
{
  "_embedded": {
    "transfers": [...] // The list of resources
  },
  "_links": {...},
  "page" : {
    "limit" : 10,
    "next_cursor" : "TRnasXQ5AmjsLnPMwnme7TL4"
  }
}

By default, Finix returns resources ordered by their creation date.

Use next_cursor to get the next set of results by either providing the cursor value in after_cursor to page forward or before_cursor to page backwards.

For instructions on how to switch your requests to cursor-based pagination, see Migrating to Cursor Pagination.

Page Forward

To page forward, provide the next_cursor value in after_cursor. This gives you the next set of results after the cursor:

bashjson
Copy
Copied
curl "https://finix.sandbox-payments-api.com/transfers?limit=10&after_cursor=TRnasXQ5AmjsLnPMwnme7TL4" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Copy
Copied
{
  "_embedded": {
    "transfers": [...] // The next set of resources
  },
  "_links": {...},
  "page" : {
    "limit" : 10,
    "next_cursor" : "TR5F6tQgR37LAN48hHiA4Mj6"
  }
}

You can continue to take the nextcursor and provide it in aftercursor to keep paging forward.

Page Backward

To page backward, provide the next_cursor value in before_cursor. This gives you the next set of results before the cursor:

bashjson
Copy
Copied
curl "https://finix.sandbox-payments-api.com/transfers?limit=10&before_cursor=TRnasXQ5AmjsLnPMwnme7TL4" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Copy
Copied
{
  "_embedded": {
    "transfers": [...] // The previous set of resources
  },
  "_links": {...},
  "page" : {
    "limit" : 10,
    "next_cursor" : "TR5F6tQgR37LAN48hHiA4Mj6"
  }
}

The next_cursor is now pointing backwards. Take the next_cursor value and provide it as before_cursor in the next query to keep paging backward.

End of Results

If the next_cursor value is null, then there are no more resources to return for the current query.