Many of our endpoints, particularly those for looking up lists of data, use pagination when returning results. Pagination provides the following benefits:

• Faster response times: less data needs to be searched through and sent over the network
• Lower data usage: less data is sent in a particular API call, this is useful if you have a slow network or a network limit
• Pick up where you left off: you can query for the next page of data later starting at the next page. Note that there may be a mismatch of data if a significant period of time has passed between calls.

By default, our endpoints have a pagination limit of 100. In other words, by default, our endpoints will return at most 100 items in a single API call. You can modify this value by specifying a limit value in a call to the appropriate endpoint.

How Does Pagination Work?

When results are returned, our systems will indicate that more information is available by including a next_start_key field in the API response. For example:

{
  "data": [{...}],
  "next_start_key": ...
}

If no next_start_key is present, then all of the results have been retrieved. Once a next_start_key has been received, it needs to be included as the next_start_key field in the next API call. You will receive a new next_start_key in each response until no more pages of data are available.

Subsequent calls to the API should have the same parameters, with only the next_start_key changing between calls

Example: Retrieve all results from an API call

Here we show how you can retrieve all of the data from an API call, using a custom page size.

import os
import requests

API_URL = "https://api.dba.thepennyinc.com/v1"
ACCESS_TOKEN = os.getenv("PENNY_API_KEY")

headers = {
    "Authorization": f"Bearer: {ACCESS_TOKEN}" 
}

parameters = {
    "limit": 10    # We only want to retrieve 10 items at a time 
}

results = []
next_start_key = None
while True:
    # If we have a next_start_key, provide it in the next API call
    if next_start_key is not None:
        parameters["next_start_key"] = next_start_key
    
    # Make the API call with the same parameters, only changing the next_start_key
    response = requests.get(API_URL + "/cards", params=parameters, headers=headers)

    # Add the results from the API call and attempt to retrieve the new next_start_key
    results.extend(response.get("data", []))
    next_start_key = response.get("next_start_key")
    
    # If there is no next_start_key, there is no more data to retrieve so we are done
    if next_start_key is None:
        break