Pagination

Overview

Endpoints that return large result sets support offset-based pagination using limit and offset query parameters. All paginated responses share the same shape.

Response format

Every paginated endpoint returns:

{
  "results": [...],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Field	Type	Description
results	array	Items for the current page
total	integer	Total number of items (before pagination)
limit	integer	Maximum items per page
offset	integer	Number of items skipped

Some endpoints include additional fields alongside the pagination (e.g., query, country, processing_time_ms).

Parameters

Parameter	Type	Default	Description
limit	integer	varies	Maximum number of items to return
offset	integer	0	Number of items to skip

Paginated endpoints

Endpoint	Default limit	Max limit
GET /v1/search	20	100
GET /v1/rankings	50	200
GET /v1/trending	20	100
GET /v1/collections/{slug}	50	200

Example: paginating through results

const PAGE_SIZE = 20;
let offset = 0;
let allResults = [];

while (true) {
  const res = await fetch(
    `https://api.popcorntime.app/v1/search?q=action&country=US&limit=${PAGE_SIZE}&offset=${offset}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await res.json();

  allResults.push(...data.results);

  if (allResults.length >= data.total || data.results.length < PAGE_SIZE) {
    break; // No more pages
  }

  offset += PAGE_SIZE;
}

Non-paginated endpoints

These endpoints return all results in a single response:

Endpoint	Typical size
GET /v1/providers	~50-200 per country
GET /v1/featured	~10-20 items
GET /v1/collections	~5-20 per country (list only)
GET /v1/media/{id}/links	~10-50 links
GET /v1/media/{id}/seasons	~1-20 seasons
GET /v1/media/{id}/seasons/{season}/episodes	~5-25 episodes
GET /v1/locales	~30 languages

Use the q parameter on /v1/providers to filter results if the full list is too large.