Input/Output Limitations

Understand the constraints on input and output data sizes for Altitude APIs, including limits on data returned and methods to adjust record counts.

  • Each input parameter must be no more than 1 MB of data.
  • APIs can only return a maximum of 10 MB of data per page. Use the pageSize query parameter to control how many records are returned per page (1 to 20,000; defaults to the maximum when omitted).
Note:

Some analytical endpoints follow a two-step async pattern and return results as a paginated job result. See API Workflow for details.

Paginating results

When more results are available than fit on a single page, the response includes a Link response header containing an RFC 8288 rel="next" URL, and an Altitude-Next-Page-Token header carrying the same token value directly. Both headers are present only when another page exists.

How you handle pagination depends on whether you are calling the REST API directly or using the altitude-sdk Python package.

Direct REST API calls: extract the pageToken value from the Link header URL, or read it directly from the Altitude-Next-Page-Token header, and pass it as a query parameter on your next request. Omit pageToken on your first request. Continue requesting pages until a response does not include either header.

Request the first page:

GET /api/v2/{endpoint}/{id}?pageSize=5000
Authorization: Bearer <your-api-key>

If more results remain, the response includes a Link header similar to:

Link: </api/v2/{endpoint}/{id}?pageSize=5000&pageToken=abc123>; rel="next"

Extract the token (abc123 in this example) and include it in your next request:

GET /api/v2/{endpoint}/{id}?pageSize=5000&pageToken=abc123
Authorization: Bearer <your-api-key>

Repeat until a response is returned without a Link or Altitude-Next-Page-Token header.

altitude-sdk (Python): the SDK does not expose the page-token headers to your code - pagination is handled internally. Use the job handler's .pages() iterator to loop through pages, or .all() if you want every row returned in one call without iterating yourself.

import time

wf = client.stop_analytics.rda(params)

wf.run()  # submit the job (non-blocking); sets wf.id

while True:

    status = wf.status()["status"]

    if status == "FAILED":

        raise RuntimeError(f"Job {wf.id} failed")

    if status == "CANCELED":

        raise RuntimeError(f"Job {wf.id} was canceled")

    if status == "DONE":

        break

    time.sleep(5)

rows = []

for page in wf.pages():

    rows.extend(page.data)
Previous
Next