Pagination

This tutorial describes how to use the Limit and Offset parameters to page through API result sets.

Introduction

Pagination is the process of dividing a total results set into smaller subsets for display in a user-interface.

Limit and offset

The Bazaarvoice platform calculates a total result set each time a request is made using the Conversations API. The total result set can be paginated using the Limit and Offset parameters. Limit controls the count of results that will be returned in response to a request. Offset identifies the position within the total result to start returning results. By combining these two parameters it is possible to iterate through a total result set.

ParametersDescription
LimitMax count of records to return per request. The default is 10 andthe max 100.
OffsetIndex at which to return results. By default, indexing begins at 0 when you issue a query. Using Limit=100&Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000.

❗️

Limit and Offset are intended for use with organic traffic (users manually clicking links) only. Any other usage will cause performance degradation and may result in restrictions or limitations on API usage.

Basic pagination

The following table demonstrates basic pagination. In this example each page shows the same number of results. The highlighted sections depict the subset that will be returned for a given page.

Request / PageParametersTotal results count
1
&Limit=5&Offset=0
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
2
&Limit=5&Offset=5
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
3
&Limit=5&Offset=10
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14

Best practice pagination

As a best practice we recommend displaying less user generated content (UGC) on the first page, and then more after a user has indicated an interest in reading UGC by initiating pagination. Specifically you should display no
fewer than 8 results on the first page and up to 30 results on subsequent pages.

In this example the first page shows a lower number of results than subsequent pages. This is accomplished by modifying the Limit and Offset parameter values. The highlighted sections depict the subset that will be returned for a given page.

Request / PageParametersTotal results count
1
&Limit=5&Offset=0
0 1 2 3 45 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
2
&Limit=10&Offset=5
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
3
&Limit=10&Offset=15
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

📘

For simplicity the example above starts with 5 results on the first page and then 10 results on subsequent pages. Our official recommendation is no fewer than 8 results on the first page and then up to 30 results on subsequent pages.