Paginationlink

The Infraspeak API uses page-based pagination for endpoints that return collections. This guide explains how to efficiently navigate large datasets.

Requests that return multiple items will be paginated to 200 items by default. It's possible to change this value by specifying the limit parameter.

Page number is 1-based and omitting the page parameter will return the first page.

Pagination Parameterslink

Basic Usagelink

# Get first page with default size (200)
curl "https://api.infraspeak.com/v3/failures" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get specific page with default size (200)
curl "https://api.infraspeak.com/v3/failures?page=2" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get specific page with custom page size
curl "https://api.infraspeak.com/v3/failures?limit=50&page=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Pagination Responselink

Every paginated response includes pagination metadata:

{
  "data": [
    ...
  ],
  "meta": {
    "pagination": {
      "total": 150,
      "count": 150,
      "per_page": 200,
      "current_page": 2,
      "total_pages": 3
    }
  },
  "links": {
    "self": "https://api.infraspeak.com/v3/failures?page=2",
    "first": "https://api.infraspeak.com/v3/failures?page=1",
    "prev": "https://api.infraspeak.com/v3/failures?page=1",
    "next": "https://api.infraspeak.com/v3/failures?page=3",
    "last": "https://api.infraspeak.com/v3/failures?page=3"
  }
}

Pagination Fieldslink

Navigation Linkslink

Iterating Through Pageslink

To determine if you should retrieve the next page, you can count the number of items in the current page and compare it to the limit in use: if they are the same, retrieve the next page; if the number of items in the current page is less than the limit in use, you have reached the last page.

import requests

def get_all_failures(token):
    """Fetch all failures across all pages."""
    base_url = "https://api.infraspeak.com/v3/failures"
    headers = {"Authorization": f"Bearer {token}"}
    all_failures = []
    current_page = 1
    per_page = 200

    while True:
        response = requests.get(
            base_url,
            headers=headers,
            params={
                "page": current_page,
                "limit": per_page
            }
        )

        response.raise_for_status()

        data = response.json()
        failures = data.get("data", [])

        all_failures.extend(failures)

        print(f"Page {current_page} - fetched {len(failures)} items")

        # If returned items are less than the limit,
        # we've reached the last page
        if len(failures) < per_page:
            break

        current_page += 1

    return all_failures

# Usage
failures = get_all_failures("YOUR_TOKEN")

Pagination with Filterslink

Combine pagination with filters for efficient queries:

# Get page 2 of open failures at a specific location
curl "https://api.infraspeak.com/v3/failures/open?s_local_id=12345&page=2&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practiceslink

• Use appropriate page sizes.
• Combine pagination with filters to increase performance.
• Handle empty pages.
• Respect rate limits.

Common Issueslink

Page Out of Rangelink

Requesting a page beyond the total pages returns an empty array:

{
  "data": [],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "per_page": 200,
      "current_page": 5,
      "total_pages": 6
    }
  }
}

Exceeding Maximum Page Sizelink

Using limit values above 2000 are capped at 2000:

# This returns 2000 records, not 5000
curl "https://api.infraspeak.com/v3/failures?limit=5000" \
  -H "Authorization: Bearer YOUR_TOKEN"