- Content
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:
Parameter | Description |
---|---|
ids |
Filter results by their IDs. Up to 200 IDs can be passed at once as a comma separated string. e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,... |
limit |
The number of records to include in each API page response. Allowed values: 1 to 200 Default: 20 |
order |
The ordering to use with the sort parameter.Allowed values: desc and asc Default: desc |
sort |
The field to sort responses by. Allowed values: created_at and updated_at Default: created_at |
begin_time |
Filter to only return records with a sort timestamp equal to or after the specified value.Allowed values: ISO8601 formatted timestamp |
end_time |
Filter to only return records with a sort timestamp equal to or before the specified value.Allowed values: ISO8601 formatted timestamp |
The timestamp specified in the begin_time
and end_time
parameters will default to UTC if the value does not contain a time zone.
The timestamp 2020-01-01
will be treated as 2020-01-01T00:00:00Z
by Recurly API, which may not match your expectations.
If the sort
parameter is set to updated_at
, then the order
should likely be set to asc
to avoid concurrently updated records from being moved behind the cursor and therefore excluded from the results.
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:
Key | Description |
---|---|
object |
This will always be the value list . |
has_more |
Boolean indicating whether there are more pages of responses. |
next |
The URL to request the next page of results. |
data |
An array of requested records containing between 0 and limit records per-response. |
The next
URL will contain all of the query parameters in the original request, as well as a cursor
parameter that is used to identify the starting point of the next page of results.
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.
The client libraries accept the ids
request parameter as an array of values that will be automatically converted to the comma separated string that Recurly API expects.
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).
The limit
parameter will only impact the number of records that are returned in each API page response. The Pager
will continue to request additional pages until the entire result set has been exhausted.
A lower limit
value might be preferrable to reduce request/response times.
Node.js
Python
Dotnet
Ruby
Java
PHP
Go
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.
Node.js
Python
Dotnet
Ruby
Java
PHP
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.
Node.js
Python
Dotnet
Ruby
Java
PHP
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()}");
The client library will modify the supplied limit
parameter when performing the request for the first
record to minimize request/response times. Subsequent use of the same Pager
instance will use the originally provided limit
value.
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.
Node.js
Python
Dotnet
Ruby
Java
PHP
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()}");
The client library will modify the supplied limit
parameter when performing the request for the first
record to minimize request/response times. Subsequent use of the same Pager
instance will use the originally provided limit
value.