We provide the ability to paginate all our list endpoints, e.g. listing employees, users and jobs, unless otherwise stated. This does not apply to any asynchronous data exports, e.g. exporting employee assumptions. Our pagination scheme consists of two parts: query parameters and a specific response body structure.
Query Parameters
| Query Parameter | Description | Example Usage |
|---|---|---|
| limit | The maximum number of results to return. Default is 50, with a maximum of 1000. | /employees/?limit=50 |
| offset | The number of results to offset your request by. For example, if you wanted to skip the first 50 results, you would set offset=50. | /employees/?offset=50 |
These optional parameters may be combined together to request specific subsets of data, e.g. /employees/?limit=100&offset=200.
Paginated Response Body
Response Body Properties
| Property | Data Type | Description | Example Value |
|---|---|---|---|
| next | string | null | The url for the next set of results. null if there are no additional results. | "https://api.captivateiq.com/ciq/v1/employees/?limit=50&offset=50" |
| previous | string | null | The url for the previous set of results. null if you are at the beginning. | "https://api.captivateiq.com/ciq/v1/employees/?limit=50&offset=0" |
| total_count | integer | The number of total results available. | 115 |
| data | array of objects | The requested data. |
Example Response
{
"object": "list",
"next": "/ciq/v1/employees/?limit=50&offset=50",
"previous": null,
"total_count": 115,
"data": [
...
]
}
Example Usage: Fetching All Data
To fetch all data for a given resource, after submitting the initial request, keep iterating until the next property is null.
import requests
headers = {
'Authorization': 'Token mytokenvalue'
}
url = 'https://api.captivateiq.com/ciq/v1/employees/'
# `limit` query parameter is optional. The default value is 50 and max is 1000.
response = requests.get(f'{url}?limit=100', headers=header)
body = response.json()
employees = body['data']
# `next` will continue to have a value until no more data is left.
while body['next'] is not None:
response = requests.get(body['next'], headers=headers)
body = response.json()
employees += body['data']
print('All employees:', employees)