Concepts
Pagination
Cursor pagination with starting_after, ending_before, and the id field.
The reporting API uses cursor pagination. Each result row has an id field; you advance through pages by passing the id of a row you’ve already seen as a cursor.
Query parameters
| Parameter | Description |
|---|---|
max | Maximum rows per page. Default 50, maximum 500. |
starting_after | Return rows whose id is greater than this. Use to advance forward. |
ending_before | Return rows whose id is less than this. Use to step backward. |
starting_after and ending_before are mutually exclusive. Provide at most one.
Following links
When more pages exist, the response includes _links.next and/or _links.prev already containing the right cursor — just follow the URL:
"_links": {
"self": { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50", "method": "GET" },
"next": { "href": "https://c1.emailgistics.com/api/v1/reports/results/64cbb039-...?max=50&starting_after=10027", "method": "GET" }
}This is the recommended way to paginate. You don’t need to construct cursors yourself.
When total is known
The envelope’s result.total is the total number of rows across all pages, when it can be determined cheaply. For some reports this is null until you have paginated through to the end.
Iterating through every page
url = response["_links"]["self"]["href"]
while url:
response = http_get(url)
for row in response["result"]["data"]:
process(row)
url = response["_links"].get("next", {}).get("href") # stop when there's no next linkSee also
- Result envelope — where
_links.nextand_links.prevcome from. - The endpoint reference pages document which endpoints are paginated.