Pagination

Ticksupply uses cursor-based pagination for endpoints that return lists of items. This approach provides stable, consistent results even when data changes between requests.

How pagination works

Paginated endpoints accept two query parameters:

Parameter	Type	Description
`limit`	integer	Number of items per page (see limits below)
`page_token`	string	Cursor for the next page (from previous response)

Default limits vary by endpoint:

Endpoints	Default	Max
Subscriptions, Exports	50	100
Instruments, Datastreams	100	1,000

The response includes pagination metadata:

{
  "items": [...],
  "total": 150,
  "limit": 50,
  "next_page_token": "eyJpZCI6IjEyMzQ1IiwidHMiOiIyMDI0LTEyLTIxIn0="
}

Field	Description
`items`	Array of results for the current page
`total`	Total number of items across all pages
`limit`	Items per page (as requested)
`next_page_token`	Token for the next page (null if no more pages)

Basic pagination

First page

Request the first page without a page_token:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.ticksupply.com/v1/subscriptions?limit=10"

Response:

{
  "items": [
    {"id": "sub_0194a1b2c3d47e5fa7b8c9d0e1f2a3b4", "status": "active", ...},
    {"id": "sub_0194b2c3d4e57f6ab8c9d0e1f2a3b4c5", "status": "active", ...},
    // ... 8 more items
  ],
  "total": 47,
  "limit": 10,
  "next_page_token": "eyJ0cyI6IjIwMjQtMTItMjFUMTI6MDA6MDBaIiwiaWQiOiIwMTk0YTFiMi1jM2Q0LTdlNWYtYTdiOC1jOWQwZTFmMmEzYjQifQ"
}

Subsequent pages

Use the next_page_token from the previous response:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.ticksupply.com/v1/subscriptions?limit=10&page_token=eyJ0cyI6IjIwMjQtMTItMjFUMTI6MDA6MDBaIiwiaWQiOiIwMTk0YTFiMi1jM2Q0LTdlNWYtYTdiOC1jOWQwZTFmMmEzYjQifQ"

Last page

When there are no more items, next_page_token is null:

{
  "items": [
    {"id": "sub_0194c3d4e5f6708a9bcadb1e2f3a4b5c", "status": "paused", ...},
    // ... remaining items
  ],
  "total": 47,
  "limit": 10,
  "next_page_token": null
}

Complete pagination example

def fetch_all_subscriptions():
    """Fetch all subscriptions using pagination."""
    all_subscriptions = []
    page_token = None
    
    while True:
        params = {"limit": 100}
        if page_token:
            params["page_token"] = page_token
        
        response = requests.get(
            "https://api.ticksupply.com/v1/subscriptions",
            headers={"X-Api-Key": API_KEY},
            params=params
        )
        response.raise_for_status()
        data = response.json()
        
        all_subscriptions.extend(data["items"])
        print(f"Fetched {len(all_subscriptions)}/{data['total']} subscriptions")
        
        page_token = data.get("next_page_token")
        if not page_token:
            break
    
    return all_subscriptions

# Usage
subscriptions = fetch_all_subscriptions()
print(f"Total: {len(subscriptions)} subscriptions")

async function fetchAllSubscriptions() {
  const allSubscriptions = [];
  let pageToken = null;
  
  while (true) {
    const params = new URLSearchParams({ limit: "100" });
    if (pageToken) {
      params.set("page_token", pageToken);
    }
    
    const response = await fetch(
      `https://api.ticksupply.com/v1/subscriptions?${params}`,
      { headers: { "X-Api-Key": API_KEY } }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    const data = await response.json();
    allSubscriptions.push(...data.items);
    
    console.log(`Fetched ${allSubscriptions.length}/${data.total} subscriptions`);
    
    pageToken = data.next_page_token;
    if (!pageToken) break;
  }
  
  return allSubscriptions;
}

// Usage
const subscriptions = await fetchAllSubscriptions();
console.log(`Total: ${subscriptions.length} subscriptions`);

Generator pattern

For memory efficiency with large datasets, use a generator pattern:

def iter_subscriptions(limit=100):
    """Iterate through subscriptions one at a time."""
    page_token = None
    
    while True:
        params = {"limit": limit}
        if page_token:
            params["page_token"] = page_token
        
        response = requests.get(
            "https://api.ticksupply.com/v1/subscriptions",
            headers={"X-Api-Key": API_KEY},
            params=params
        )
        response.raise_for_status()
        data = response.json()
        
        for item in data["items"]:
            yield item
        
        page_token = data.get("next_page_token")
        if not page_token:
            break

# Usage - processes one item at a time
for subscription in iter_subscriptions():
    process_subscription(subscription)

async function* iterSubscriptions(limit = 100) {
  let pageToken = null;
  
  while (true) {
    const params = new URLSearchParams({ limit: String(limit) });
    if (pageToken) {
      params.set("page_token", pageToken);
    }
    
    const response = await fetch(
      `https://api.ticksupply.com/v1/subscriptions?${params}`,
      { headers: { "X-Api-Key": API_KEY } }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    const data = await response.json();
    
    for (const item of data.items) {
      yield item;
    }
    
    pageToken = data.next_page_token;
    if (!pageToken) break;
  }
}

// Usage - processes one item at a time
for await (const subscription of iterSubscriptions()) {
  await processSubscription(subscription);
}

Cursor stability

Cursor-based pagination provides stable results:

Items aren't skipped or duplicated

Unlike offset-based pagination, cursor pagination doesn’t skip items when new data is added or duplicates items when data is deleted.

Consistent ordering

Results are ordered by creation time (newest first) and ID. This ordering remains stable across pages.

Cursors are opaque

Treat page tokens as opaque strings. Don’t parse, modify, or construct them—only use tokens returned by the API.

Page tokens may expire after extended periods. If you receive an error with an old token, start from the first page.

Best practices

Use appropriate page sizes

Small datasets: Use default limits or smaller for quick responses
Bulk operations: Use maximum limit (100 for subscriptions/exports, 1,000 for catalog) to reduce API calls
UI pagination: Match your UI’s display capacity

# For listing in UI
response = requests.get(url, params={"limit": 20})

# For bulk processing
response = requests.get(url, params={"limit": 100})

Handle rate limits during pagination

When paginating large datasets, implement rate limit handling:

def fetch_all_with_rate_limit(endpoint, limit=100):
    all_items = []
    page_token = None
    
    while True:
        params = {"limit": limit}
        if page_token:
            params["page_token"] = page_token
        
        response = requests.get(
            endpoint,
            headers={"X-Api-Key": API_KEY},
            params=params
        )
        
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 30))
            print(f"Rate limited, waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        response.raise_for_status()
        data = response.json()
        
        all_items.extend(data["items"])
        page_token = data.get("next_page_token")
        
        if not page_token:
            break
    
    return all_items

Don’t store page tokens long-term

Page tokens are meant for immediate pagination, not long-term storage:

# ✅ Good: Use immediately
data = fetch_page_1()
data_2 = fetch_page_2(data["next_page_token"])

# ❌ Bad: Store for later
save_to_database(data["next_page_token"])  # May expire

Paginated endpoints

Endpoint	Default limit	Max limit
`GET /v1/subscriptions`	50	100
`GET /v1/exports`	50	100
`GET /v1/exchanges/{exchange}/instruments`	100	1,000
`GET /v1/datastreams`	100	1,000
`GET /v1/exchanges/{exchange}/datastreams`	100	1,000
`GET /v1/exchanges/{exchange}/instruments/{instrument}/datastreams`	100	1,000

Next steps

Error Handling

Handle API errors gracefully in your application

Rate Limiting

Understand rate limits and how to handle them

Idempotency

Safely retry requests using idempotency keys

API Reference

Explore the complete API documentation

Getting Started

Guides

Examples

Pagination

First page

Subsequent pages

Last page

Generator pattern

Cursor stability

Best practices

Use appropriate page sizes

Don’t store page tokens long-term

Paginated endpoints

Next steps

Error Handling

Rate Limiting

Idempotency

API Reference

​Pagination

​How pagination works

​Basic pagination

​First page

​Subsequent pages

​Last page

​Complete pagination example

​Generator pattern

​Cursor stability

​Best practices

​Use appropriate page sizes

​Handle rate limits during pagination

​Don’t store page tokens long-term

​Paginated endpoints

​Next steps

Error Handling

Rate Limiting

Idempotency

API Reference

Pagination

How pagination works

Basic pagination

First page

Subsequent pages

Last page

Complete pagination example

Generator pattern

Cursor stability

Best practices

Use appropriate page sizes

Handle rate limits during pagination

Don’t store page tokens long-term

Paginated endpoints

Next steps