How to paginate YouTube API results

TL;DR

YouTube API responses include nextPageToken and prevPageToken fields for navigating result pages. Pass the token as a pageToken parameter in your next request. Each page returns up to 50 items (configurable via maxResults). Each paginated request costs the same quota as the first. BrightBean’s API handles pagination internally and returns complete result sets.

How to paginate YouTube API results

YouTube API endpoints that return lists (search, playlists, comments, etc.) use token-based pagination. Here’s how it works:

Step 1: Make your initial request. The response includes pageInfo (total results and results per page) and a nextPageToken string.

Step 2: To get the next page, include pageToken=NEXT_TOKEN in your follow-up request. Everything else stays the same.

Step 3: Repeat until nextPageToken is absent from the response, indicating you’ve reached the last page.

Key details:

• maxResults controls items per page (1 to 50, default varies by endpoint)
• totalResults in pageInfo is an estimate and can change between pages
• Each paginated request costs the same quota as the original request
• Page tokens are opaque strings, so don’t try to modify or predict them
• Tokens expire after a few hours, so don’t store them long-term

For the search.list endpoint, pagination gets expensive quickly. 10 pages of search results = 1,000 quota units. For videos.list or commentThreads.list, it’s much cheaper at 1 unit per page.

A common pattern: use search to find video IDs (expensive), then use videos.list with batched IDs (cheap) to get full details. This minimizes search pagination while still getting complete data.

How BrightBean helps

BrightBean handles pagination internally. When you request trending topics or search results, you get complete result sets without managing tokens.

GET /trending?niche=gaming&limit=50

{
  "results": 50,
  "topics": [...],
  "has_more": true,
  "cursor": "eyJwIjoyLCJuIjoiZ2FtaW5nIn0"
}

BrightBean uses cursor-based pagination, which is simpler and more reliable than YouTube’s token-based approach. Just pass the cursor value to get the next batch.

Key takeaways

• YouTube API uses nextPageToken/prevPageToken for pagination
• Each paginated request costs the same quota as the first request
• maxResults can be set from 1 to 50 items per page
• totalResults is an estimate and may change between requests
• BrightBean handles pagination internally and uses cursor-based navigation

Related questions

• What is the YouTube Data API v3?
• YouTube API rate limits — how to avoid quota errors