Pagination

When your site has thousands of records, fetching all records in a single request becomes inefficient and may negatively impact performance. To address this, the Recurly API provides paginated list_* operations, allowing you to retrieve records in manageable chunks across multiple API requests.

Request Parameters

Most list_* operations accept the following parameters to control pagination:

• limit (optional): Specifies the maximum number of records to return in each response. The default value may vary depending on the endpoint.
• order (optional): Determines the order in which the records are returned, typically sorted by creation date or another relevant field. Valid values are asc (ascending) and desc (descending).
• begin_time (optional): Returns only records created after this date. This parameter allows you to filter records by a specific time range.
• end_time (optional): Returns only records created before this date, enabling further control over the range of data returned.
• sort (optional): Specifies the field by which the results are sorted.

Pagination results include metadata in the response to help you manage subsequent API calls, such as:

• next: A URL to retrieve the next set of results.
• has_more: A boolean value indicating whether more records are available beyond the current page.

The API Reference documentation will provide detailed information about any additional parameters that a particular list_* operation supports.

JSON response format

Each response from Recurly API will contain the following keys in the JSON object that is returned:

Client library pagers

The client libraries for Recurly API provide a Pager class that provides the capability to iterate over all of the records for a given endpoint without the need to manually perform each pagination request.

An instance of a Pager class is immediately returned when calling any of the list_* methods. A request to Recurly API will only occur when your code begins to iterate over the results or one of the other convenience methods is invoked.

Iterating with pagers

The primary purpose of the Pager is to provide a mechanism to automatically iterate over all of the records that are available. The Pager will continue to perform requests to Recurly API for more pages of results, as necessary, until the response indicates that there are no more pages available (has_more is false).

const accounts = client.listAccounts({ limit: 200 })

for await (const account of accounts.each()) {
  console.log(account.code)
}

accounts = client.list_accounts(limit=200).items()

for account in accounts:
    print(account.code)

var accounts = client.ListAccounts(limit: 200);

foreach(Account account in accounts)
{
    Console.WriteLine(account.Code);
}

accounts = @client.list_accounts(limit: 200)

accounts.each do |account|
  puts account.code
end

QueryParams params = new QueryParams();
params.setLimit(200);
Pager<Account> accounts = client.listAccounts(params);

for (Account account : accounts) {
    System.out.println(account.getCode());
}

$accounts = $client->listAccounts([ 'limit' => 200 ]);

foreach($accounts as $account) {
    echo $account->getCode() . PHP_EOL;
}

listParams := &recurly.ListAccountsParams{
	Limit: recurly.Int(200),
}
accounts := client.ListAccounts(listParams)

for accounts.HasMore {
	err := accounts.Fetch()
	if e, ok := err.(*recurly.Error); ok {
		fmt.Printf("Failed to retrieve next page: %v", e)
		break
	}
	for _, account := range accounts.Data {
		fmt.Println(account.Code)
	}
}

Total record count

The total number of records for a given set of request parameters can be quickly determined using the count method of the Pager without needing to fetch and iterate over the entire result set. This will perform a HEAD request to Recurly API and return the Recurly-Total-Records header value.

const beginTime = new Date('January 1, 2020')
const accounts = await client.listAccounts({
    limit: 200,
    sort: 'created_at',
    beginTime: beginTime
})
const count = await accounts.count()

console.log(`Accounts created since ${beginTime}: ${count}`)

begin_time = datetime(2020, 1, 1, 0, 0, 0)
accounts = client.list_accounts(
    limit=200,
    sort='created_at',
    begin_time=begin_time
)
count = accounts.count()

print(f"Accounts created since {begin_time}: {count}")

var beginTime = new DateTime(2020, 1, 1);
var accounts = client.ListAccounts(
    limit: 200,
    sort: "created_at",
    beginTime: beginTime
);
var count = accounts.Count();

Console.WriteLine($"Accounts created since {beginTime}: {count}");

begin_time = DateTime.new(2020, 1, 1)
accounts = @client.list_accounts(
    limit: 200,
    sort: 'created_at',
    begin_time: begin_time
)
count = accounts.count

puts "Accounts created since #{begin_time}: #{count}"

DateTime beginTime = new DateTime(2020, 1, 1, 0, 0);
QueryParams params = new QueryParams();
params.setLimit(200);
params.setSort("created_at");
params.setBeginTime(beginTime);

Pager<Account> accounts = client.listAccounts(params);
int count = accounts.getCount();

System.out.println("Accounts created since " + beginTime + ": " + count);

$beginTime = new DateTime("2020-01-01 00:00:00");
$accounts = $client->listAccounts([
    'limit' => 200,
    'sort' => 'created_at',
    'begin_time' => $beginTime
]);
$count = $accounts->getCount();

print("Accounts created since {$beginTime->format('Y-m-d')}: $count");

Getting the first record

If you are only interested in the first record that matches the supplied request parameters, then the first method of the Pager can be used. If there are no matching records, then a null value will be returned.

const beginTime = new Date('January 1, 2020')
const accounts = await client.listAccounts({
    limit: 200,
    sort: 'updated_at',
    order: 'asc',
    beginTime: beginTime
})
const account = await accounts.first()

console.log(`First Account updated since ${beginTime}: ${account.code}`)

begin_time = datetime(2020, 1, 1, 0, 0, 0)
accounts = client.list_accounts(
    limit=200,
    sort='updated_at',
    order='asc',
    begin_time=begin_time
)
account = accounts.first()

print(f"First Account updated since {begin_time}: {account.code}")

var beginTime = new DateTime(2020, 1, 1);
var accounts = client.ListAccounts(
    limit: 200,
    sort: "updated_at",
    order: "asc",
    beginTime: beginTime
);
var account = accounts.First();

Console.WriteLine($"First Account updated since {beginTime}: {account.Code}");

begin_time = DateTime.new(2020, 1, 1)
accounts = @client.list_accounts(
    limit: 200,
    sort: 'updated_at',
    order: 'asc',
    begin_time: begin_time
)
account = accounts.first

puts "First Account updated since #{begin_time}: #{account.code}"

DateTime beginTime = new DateTime(2020, 1, 1, 0, 0);

QueryParams params = new QueryParams();
params.setLimit(200);
params.setSort("updated_at");
params.setOrder("asc");
params.setBeginTime(beginTime);
Pager<Account> accounts = client.listAccounts(params);
Account account = accounts.getFirst();

System.out.println("First Account updated since " + beginTime + ": " + account.getCode());

$beginTime = new DateTime("2020-01-01 00:00:00");
$accounts = $client->listAccounts([
    'limit' => 200,
    'sort' => 'updated_at',
    'order' => 'asc',
    'begin_time' => $beginTime
]);
$account = $accounts->getFirst();

print("First Account updated since {$beginTime->format('Y-m-d')}: {$account->getCode()}");

Getting the last record

While there is not an explicity defined last method, the equivalent request can be accomplished by changing the order parameter of the request when using the first method.

If you are only interested in the first record that matches the supplied request parameters, then the first method of the Pager can be used. If there are no matching records, then a null value will be returned.

const endTime = new Date('January 1, 2020')
const accounts = await client.listAccounts({
    limit: 200,
    sort: 'updated_at',
    order: 'desc',
    endTime: endTime
})
const account = await accounts.first()

console.log(`Last Account updated before ${endTime}: ${account.code}`)

end_time = datetime(2020, 1, 1, 0, 0, 0)
accounts = client.list_accounts(
    limit=200,
    sort='updated_at',
    order='desc',
    end_time=end_time
)
account = accounts.first()

print(f"Last Account updated before {end_time}: {account.code}")

var endTime = new DateTime(2020, 1, 1);
var accounts = client.ListAccounts(
    limit: 200,
    sort: "updated_at",
    order: "desc",
    endTime: endTime
);
var account = accounts.First();

Console.WriteLine($"Last Account updated before {endTime}: {account.Code}");

end_time = DateTime.new(2020, 1, 1)
accounts = @client.list_accounts(
    limit: 200,
    sort: 'updated_at',
    order: 'desc',
    end_time: end_time
)
account = accounts.first

puts "Last Account updated before #{end_time}: #{account.code}"

DateTime endTime = new DateTime(2020, 1, 1, 0, 0);

QueryParams params = new QueryParams();
params.setLimit(200);
params.setSort("updated_at");
params.setOrder("desc");
params.setEndTime(endTime);
Pager<Account> accounts = client.listAccounts(params);
Account account = accounts.getFirst();

System.out.println("Last Account updated before " + endTime + ": " + account.getCode());

$endTime = new DateTime("2020-01-01 00:00:00");
$accounts = $client->listAccounts([
    'limit' => 200,
    'sort' => 'updated_at',
    'order' => 'desc',
    'end_time' => $endTime
]);
$account = $accounts->getFirst();

print("Last Account updated before {$endTime->format('Y-m-d')}: {$account->getCode()}");