Using pagination with the API

When dealing with extensive data, such as search results or database queries, it's impractical to load all results in a single request due to performance and usability concerns. This is where pagination, a key concept in API design, comes into play. Pagination allows for dividing data into manageable chunks or "pages," improving the performance and user experience. This article delves into the mechanics of pagination, particularly focusing on its implementation in APIs.

Understanding Pagination in API Responses

Initial Call and Metadata

When you initiate a request to an API that supports pagination, the response typically includes essential metadata. This metadata within a meta object at the response's end contains critical information like total_items. The "total_items" variable indicates the results available based on the applied filters and parameters.

The Pagination Process

The Jungle Scout API provides a mechanism to request additional results to access subsequent chunks of data. At the end of each response, the "next" variable is present if there are more than 100 results. This variable contains a URL that can be used to make another call to the API, fetching the next set of results, commonly in batches of 100 items.

This process continues, with each response providing a new next link, until you reach the end of the total results. Once there are no more results to fetch, the response will no longer include a value in the "next" variable.

Automation and Efficiency

Implementing a system automatically following these next links to fetch all results is straightforward. However, fetching all available data might be impractical or unnecessary for some use cases, which is why it's valuable to set specific thresholds, or filters, before fetching the data.

Setting Thresholds

Setting certain thresholds based on relevant metrics, such as a minimum revenue or search volume, is advisable to tailor the data to a use case. This approach ensures that the data fetching process continues only if the results meet the set criteria, which increases the relevancy of the results and efficiency of API call usage.

Pagination Parameters and Endpoint Behavior

Controlling Page Size

APIs offering pagination often allow control over the size of each data chunk through a page[size] query parameter. This parameter lets you specify the number of records you wish to receive per page. However, it's important to note that different endpoints might have varying maximum limits for page sizes, typically documented in the API's endpoint documentation section. In almost all cases, setting the size parameter to the maximum value of 100 will be most beneficial.

Cursor-based Pagination

Our APIs use cursor-based pagination for performance optimization. In this approach, the response includes a page cursor, restricting navigation to sequential pages rather than allowing random access to any page. The cursor value, used for pagination, is returned in the response as part of the links[next] attribute.

Specific Endpoint Pagination

Certain endpoints, such as Keywords_by_asin_query, Keywords_by_keyword_query, and Product_database_query, require pagination due to the volume of data they handle. For these endpoints, understanding and implementing pagination is crucial. On the other hand, endpoints such as historical_search_volume, sales estimates, and share_of_voice, return all results in a single response, eliminating the need for pagination.


Pagination is a fundamental aspect of modern API design, essential for handling large datasets efficiently. By understanding how pagination works, including using metadata, navigation through next links, setting thresholds for data relevance, and utilizing cursor-based approaches, developers can effectively manage and interact with extensive data sets. 

Was this article helpful?
0 out of 0 found this helpful