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:

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'

/** 
 * See installation instructions at 
 * https://developers.circle.com/developer/docs/circle-sdk
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
    '<your-api-key>',
    CircleEnvironments.sandbox
);

async function listPayments() {
    const resp = await circle.payments.listPayments(
        // Skip defining other query params
        undefined, undefined, undefined, undefined, undefined,

        '2020-01-01T00:00:00Z',     // 'from' query param
        '2020-01-31T23:59:59Z',     // 'to' query param
    );
    console.log(resp.data);
}
listPayments();

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:

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'i

/** 
 * See installation instructions at 
 * https://developers.circle.com/developer/docs/circle-sdk
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
    '<your-api-key>',
    CircleEnvironments.sandbox      // API base url
);

async function listPayments() {
    const resp = await circle.payments.listPayments(
        // Skip defining other query params
        undefined, undefined, undefined, undefined, undefined, undefined,

        '2020-01-31T23:59:59Z',                     // 'to' query param
        undefined,                                  // skip 'pageBefore' query param
        '5c5abf90-b2ad-4c8c-8ce3-dbb6a06a040e'      // 'pageAfter' query param
    );
    console.log(resp.data);
}
listPayments();

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

/** 
 * See installation instructions at 
 * https://developers.circle.com/developer/docs/circle-sdk
 */
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
    '<your-api-key>',
    CircleEnvironments.sandbox
);

async function listPayments() {
    const resp = await circle.payments.listPayments();
    console.log(resp.data);
}
listPayments();

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.