Pagination¶

List endpoints return paginated results. This guide explains how to navigate through large result sets.

Pagination Parameters¶

All list endpoints support these query parameters:

Parameter	Type	Default	Max	Description
`offset`	integer	0	-	Number of items to skip
`limit`	integer	100	500	Maximum items to return

Basic Usage¶

First Page¶

curl "https://api.toptickets.app/v1/tickets?limit=50"

Second Page¶

curl "https://api.toptickets.app/v1/tickets?offset=50&limit=50"

Third Page¶

curl "https://api.toptickets.app/v1/tickets?offset=100&limit=50"

Python Examples¶

Simple Pagination¶

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.toptickets.app/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def get_tickets_page(offset=0, limit=50):
    """Get a single page of tickets."""
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"offset": offset, "limit": limit}
    )
    return response.json()

# Get first 50 tickets
first_page = get_tickets_page(offset=0, limit=50)

# Get next 50 tickets
second_page = get_tickets_page(offset=50, limit=50)

Iterate Through All Results¶

import requests

def get_all_tickets():
    """Fetch all tickets using pagination."""
    all_tickets = []
    offset = 0
    limit = 100  # Use max limit for efficiency

    while True:
        response = requests.get(
            f"{BASE_URL}/tickets",
            headers=HEADERS,
            params={"offset": offset, "limit": limit}
        )
        tickets = response.json()

        if not tickets:
            break  # No more results

        all_tickets.extend(tickets)

        if len(tickets) < limit:
            break  # Last page

        offset += limit

    return all_tickets

# Get all tickets
tickets = get_all_tickets()
print(f"Total tickets: {len(tickets)}")

Generator for Memory Efficiency¶

import requests

def iter_tickets(batch_size=100):
    """Iterate through all tickets without loading all into memory."""
    offset = 0

    while True:
        response = requests.get(
            f"{BASE_URL}/tickets",
            headers=HEADERS,
            params={"offset": offset, "limit": batch_size}
        )
        tickets = response.json()

        if not tickets:
            break

        for ticket in tickets:
            yield ticket

        if len(tickets) < batch_size:
            break

        offset += batch_size

# Process tickets one at a time
for ticket in iter_tickets():
    print(f"Processing ticket {ticket['ticket_number']}")

cURL Examples¶

Paginate Through Results¶

# Page 1 (items 1-50)
curl "https://api.toptickets.app/v1/tickets?offset=0&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Page 2 (items 51-100)
curl "https://api.toptickets.app/v1/tickets?offset=50&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Page 3 (items 101-150)
curl "https://api.toptickets.app/v1/tickets?offset=100&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Combining with Filters¶

Pagination works with all filter parameters:

# Get high priority open tickets, paginated
response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={
        "status": "open",
        "priority": "high",
        "offset": 0,
        "limit": 25
    }
)

# Same in cURL
curl "https://api.toptickets.app/v1/tickets?status=open&priority=high&offset=0&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices¶

1. Use the Maximum Limit¶

When fetching all records, use limit=500 (the maximum) to minimize API calls:

params = {"offset": 0, "limit": 500}  # More efficient than limit=50

2. Handle Empty Results¶

Always check for empty results to know when pagination is complete:

tickets = response.json()
if not tickets:
    print("No more results")

3. Check Result Count¶

If the number of results is less than your limit, you've reached the last page:

tickets = response.json()
if len(tickets) < limit:
    print("This is the last page")

4. Don't Rely on Total Count¶

The API doesn't return a total count. To know the total, you must paginate through all results.

5. Be Aware of Changes During Pagination¶

If records are added or deleted while you're paginating, you might: - Miss some records - See some records twice

For critical operations, consider using timestamps to track what you've processed.

Pagination vs Search¶

For finding specific records, use the search parameter instead of paginating through everything:

# Efficient: search for specific tickets
response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"search": "login error"}
)

# Inefficient: paginate and filter client-side
# (Don't do this!)

Resource-Specific Defaults¶

Different resources may have different default limits:

Resource	Default Limit	Max Limit
Tickets	100	500
Customers	50	100
Users	50	100
Teams	50	100

Always check the specific endpoint documentation for exact values.