Paging

When working with a REST API, it’s a best practice to limit the number of items you’re retrieving to a reasonable amount. Especially if you’re not interested in getting everything at once. This way your response payload is smaller, and your requests are faster.

When an endpoint supports paging, the default and maximum page size will be specified in the endpoint documentation.

Each endpoint returns a totalCount parameter at the end of the response, which contains the total number of items in the collection. Most endpoints have a default limit on the maximum number of items they return. For example, if you have 500 Objectives, but the default limit of the /goals endpoint is 100, a request like >https://app.(us./as./sa.)quantive.com/results/api/v2/goals> will return only 100 items, and a totalCount: 500 at the end, informing you there’s more than just the 100 results it retrieves by default. In this case you must use paging to get to the other items. The Quantive Results REST API supports paging using the skip and take approach. To page through a collection, pass skip and take query parameters with the desired values in your URL.

Example:

You have 500 Objectives in your account. To page through this collection use the following algorithm:

• Determine the optimum batch size. Let’s say it’s 50.
• Use the 50 as your take parameter value– this way you’re telling the API to always return only 50 items.
• Let’s also sort by dateCreated and name so we can see view when they Objectives were created, in the order of their creation.
• Make your first request with skip=0. This way you’re taking the first 50 items of your sorted collection: https://app.(us./as./sa.)quantive.com/results/api/v2/goals?take=50&fields=name,dateCreated&skip=0
• Divide the totalCount by your desired batch size – this way you’ll determine how many pages you’ll have to go through if you want to get all items.
• To get each consecutive page, set the skip parameter value to: (Batch Size) * (page number – 1). E.g., (50) * (3-1) = 100 Thus your response will show goals numbered 101-150(of totalCount) when adding skip parameter “skip=100”.
• Page 1 (first 50 items): https://app.(us./as./sa.)quantive.com/results/api/v2/goals?take=50&fields=name,dateCreated&skip=0
• Page 2 (next 50 items (51-100)): https://app.(us./as./sa.)quantive.com/results/api/v2/goals?take=50&fields=name,dateCreated&skip=50
• Page 3 (next 50 items (101-150): https://app.(us./as./sa.)quantive.com/results/api/v2/goals?take=50&fields=name,dateCreated&skip=100
• Page 4 (next 50 items (150-200): https://app.(us./as./sa.)quantive.com/results/api/v2/goals?take=50&fields=name,dateCreated&skip=150
• …

Sorting your response is a must when you are paging though a large collection of items. Otherwise, you risk getting some items more than once and omitting some items entirely.

Quantive Results API V2 – the above examples for pagination will work with Quantive Results API V2 for the goals endpoint. Other V2 endpoints may support limit as a parameter as well. Check specific endpoint documentation to determine V2 compatibility.