Pagination and Filtering

Common Filters

The following section lists and describes common query parameters that are available across most of our collection resources.

Date Ranges

The natural item order of nearly all of our collection resources is by createDate DESC. This way the most recent item is the first item of the list. However if you only want items in a specific time range, you can specify this range via from and to query parameters:

ParameterDescriptionDefault
fromInclusive start of the date range filer applied to the createDate property of the related item.* (All historic items are included)
toInclusive end of the date range filter applied to the createDate property of the related item.now() (defaults to the timestamp of request processing)

The value format for both parameters is defined as an ISO 8601 Coordinated Universal Time (UTC) string. Lets say you want to have all payments from January 2020, your request would look like this:

curl 'https://api-sandbox.circle.com/v1/payments?from=2020-01-01T00:00:00Z&to=2020-01-31T23:59:59Z'

Pagination

The amount of information accessible via Circle APIs can get quite vast. To keep things fresh and snappy all the time, our APIs will automatically paginate the returned items on all collection resources.

This section explains how to traverse through our collection APIs easily via the provided pagination cursors. In order to illustrate things, we'll fetch some payments via the Get a list of payments resource.

Here are the basic characteristics that are valuable to know when using Circle API pagination.

  1. Each API collection endpoint has its own defaults regarding to the returned page size. It is also an option to specify the required page size yourself (via the pageSize query parameter), but keep in mind that each resource also caps the returned items per page at a fixed maximum. You can check the corresponding API docs to find out about the applicable values for your specific call.

  2. The next/previous page cursors are used to navigate through a collection.

  3. The pagination cursor is inextricably linked with the filter query parameters provided when requesting the first page. If you decide to change a filter parameter, you have to restart from the first page again.

  4. Once you reach the last page, the pagination cursor won't contain a link to the next page anymore. This is when you can stop your iteration. In the same way, there is no previous page link available on the first page.

Circle APIs provide the pagination cursor information within a single HTTP Link header. The following link relations are used for pagination navigation:

RelationDescription
selfProvides the URL pointing to the current page.
firstProvides the URL pointing to the first page.
nextProvides the URL pointing to the next page. Will be omitted on the last page.
prevProvides the URL pointing to the previous page. Will be omitted on the first page.

Note: It's important to form calls with Link header values instead of constructing your own URLs.

An example pagination cursor Link header for a page of payments in our sandbox environment might look like this:

curl -I 'https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageAfter=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e'

You'll find the above specified pagination cursor information in the response headers:

Link: <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageAfter=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e>; rel="self", <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50>; rel="first", <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageAfter=6f14b84d-7a98-4675-a6b9-d7b0c1912091>; rel="next", <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageBefore=5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e>; rel="prev"

As expected for the initial request, we are in the middle of paginating through our result set an thus receive a previous and next page link. Let's check the first page and see whats different:

curl -I 'https://api-sandbox.circle.com/v1/payments

The response Link header diffs from the above example:

Link: <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:01:00Z&pageSize=50>; rel="self", <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50>; rel="first", <https://api-sandbox.circle.com/v1/payments?to=2020-06-02T12:00:00Z&pageSize=50&pageAfter=12cd8527-5270-4acd-a1d4-431bd09f2a0e>; rel="next"

Even if not specified in the request, the response pagination links have two additional query parameters set: to and pageSize. This is necessary to keep the pagination stable: Let's say you make other payments in parallel to your page traversing. This would change your first page to contain the new payments as well and thus your pages won't be the same anymore.


Did this page help you?