Pagination & Cursors

​

How Cursor Pagination Works

• Stable results: New items added to the beginning won’t cause duplicates
• Efficient: No need to skip through large offsets
• Consistent: Results remain consistent even as data updates

​

Using Cursors

{
  "payload": [...],
  "paging": {
    "limit": 10,
    "next_cursor": "eyJpZCI6Ijk4NzY1NDMyMSIsImVuZGVkX2F0IjoiMjAyNC0wNy0wNFQxMTozMDowMC4wMDBaIn0="
  },
  "meta": {...}
}

​

Basic Pagination Pattern

async function fetchAllContent(platform, profileId) {
  let cursor = null;
  const allContent = [];

  do {
    const url = `/platforms/${platform}/profiles/${profileId}/content?limit=25${cursor ? `&cursor=${cursor}` : ''}`;
    const response = await fetch(url, {
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    });

    const data = await response.json();
    allContent.push(...data.payload);

    cursor = data.paging.next_cursor;
  } while (cursor !== null);

  return allContent;
}

​

Choosing a Limit

• Minimum: 1 item
• Maximum: 25 items. A larger limit is lowered to 25
• Default: 10 items for profile and content lists, 20 for game content, 25 for brands and industries
• Credit cost: Each page is one call, charged once whatever its limit: 0.01 credit for profile, content, game content and brand lists, 0.1 credit for industry pages

​

Limit Selection Guidelines

• Whole lists: Use limit=25. A page costs the same at any size, so full pages make the fewest calls
• Real-time updates: Use smaller limits to detect new items faster

​

Cursor Stability

• Cursors don’t expire, but they may become less efficient over time
• If you pause pagination for days/weeks, consider restarting from the beginning
• Cursors encode the sort position, so changing sort order requires a new cursor

​

Endpoints with Pagination

• GET /platforms/{platform}/profiles - Browse profiles
• GET /platforms/{platform}/content - List all content
• GET /platforms/{platform}/profiles/{profile_id}/content - List content by creator
• GET /platforms/{platform}/games/{game_id}/content - List content for a game
• GET /brands - List brands by sponsorship activity
• GET /industries - List industries (36 in all, two pages at the default limit)
• GET /industries/{industry_id} - An industry’s brand ranking. Keep the same sort on every page; ranks continue across pages, so the second page starts at rank 26

​

Best Practices

• Respect rate limits: Don’t paginate too aggressively; monitor your quota usage
• Handle errors: Implement retry logic for failed pagination requests
• Store cursors: If resuming pagination, store the last cursor to avoid re-fetching data
• Batch processing: For large datasets, process items in batches rather than loading everything into memory

​

Example: Paginating Content

# First request
curl -H "x-api-key: YOUR_KEY" \
  "https://external-api.streamforge.com/platforms/twitch/content?limit=25"

# Response includes next_cursor
# Use it in the next request
curl -H "x-api-key: YOUR_KEY" \
  "https://external-api.streamforge.com/platforms/twitch/content?limit=25&cursor=eyJpZCI6Ijk4NzY1NDMyMSIsImVuZGVkX2F0IjoiMjAyNC0wNy0wNFQxMTozMDowMC4wMDBaIn0="

​

Common Pitfalls

• Assuming page numbers: There are no page numbers; only cursors
• Reusing old cursors: While stable, very old cursors may not reflect current data
• Ignoring null cursors: Always check for null to avoid infinite loops
• Not handling empty results: An empty payload array with a null cursor means no results