Pagination

When your site has thousands of records, it becomes unwieldy to be able to fetch all of the records in a single request. For this reason, Recurly API provides paginated list_* operations that facilitate fetching all of the records for a given endpoint over multiple API requests.

Request Parameters

The majority of the list_* operations accept the following parameters:

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()}");