Paginate through data

Learn how to paginate through historical transaction data

While the /transactions/get endpoint can return up to 500 transactions for an Item at a time, in many cases you may want to fetch more than 500 transactions. Let's say you're building a budgeting app and want to fetch all of a user's available transaction history in order to build a complete picture of their historical spending. Because Plaid provides up to 24 months of transaction history depending on the institution, there will frequently be more than 500 transactions available to fetch. In this guide, we'll walk through how to retrieve a user's entire available transaction history via the /transactions/get endpoint.

Verifying that transactions are available

After initializing an Item, it may take up to several minutes for all historical transactions to be available via /transactions/get. You can be notified when transactions are ready to be fetched by handling the HISTORICAL_UPDATE webhook. For more information, see Transactions webhooks. This guide will assume that historical transactions are available.

Fetching recent transactions

Transactions are returned in order of recency. If all we want to do is get the most recent 500 or fewer transactions, our call will be very simple:

1
2
3
4
5
6
7
8
9
const response = await client
.getTransactions(accessToken, '2018-01-01', '2020-02-01', {
count: 500,
})
.catch((err) => {
// handle error
});
const transactions = response.transactions;

The above example will fetch the most recent 500 transactions. If count is not specified, the default value is 100.

Fetching all available transactions

To fetch more than 500 transactions, we will need to break down our request into multiple calls to /transactions/get. For each call after the first one, we increment the optional offset parameter to indicate how much to offset our starting point by. If offset is not specified, the default value is 0. We then take the results of each call and concatenate them together into a single array.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const response = await client
.getTransactions(ACCESS_TOKEN, '2018-01-01', '2020-02-01', {})
.catch((err) => {
// handle error
});
let transactions = response.transactions;
const total_transactions = response.total_transactions;
// Manipulate the offset parameter to paginate
// transactions and retrieve all available data
while (transactions.length < total_transactions) {
const paginatedTransactionsResponse = await client.getTransactions(
ACCESS_TOKEN,
'2018-01-01',
'2020-02-01',
{
offset: transactions.length,
},
);
transactions = transactions.concat(
paginatedTransactionsResponse.transactions
);
}

In the call above, we use the total_transactions attribute of the response to know how many transactions are available. Then we repeatedly call /transactions/get, incrementing the offset each time to gather the next batch of transactions. The code above will fetch the most recent 100 transactions, followed by the next most recent 100 transactions, and so on until all transactions have been retrieved.