Pagination

Some Simkl endpoints return many items and are paginated. Paginated endpoints are marked with 📄 Pagination in the API Reference. The pagination contract is consistent across these endpoints — same page and limit query parameters, same X-Pagination-* response headers, same cap on page (max 20) — but the default and maximum limit differ per endpoint family. Always check the per-endpoint defaults below before assuming a value.

Per-endpoint defaults

Endpoint family	Default `limit`	Max `limit`	Max `page`
`GET /search/{type}` (text search)	10	50	20
`GET /tv/genres/...`, `GET /anime/genres/...`, `GET /movies/genres/...` (by genre)	60	60	20
`GET /tv/premieres/{param}`, `GET /anime/premieres/{param}`	60	60	20

page defaults to 1 on every paginated endpoint.

Endpoints not listed here either don’t paginate (they use a different model — GET /sync/all-items uses date_from for incremental sync) or accept a much larger fixed window (e.g. GET /sync/playback returns up to 10,000 items in one shot). When in doubt, check the endpoint’s own reference page.

Query parameters

Parameter	Type	Description
`page`	integer (1–20)	Which page to return. Defaults to `1`.
`limit`	integer (1–max)	Items per page. Default and maximum vary per endpoint — see the table above.

# Page 2 of TV genre browse, 60 items per page (the max for this endpoint).
curl "https://api.simkl.com/tv/genres/all/all/all/all/all/popularity?page=2&limit=60&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"

If you pass a limit above the endpoint’s cap, the server silently clamps it down — no error, no warning, just fewer items than you asked for. Same for page above 20. Read the response headers to know what you actually got.

Response headers

Every paginated response includes:

Header	Meaning
`X-Pagination-Page`	The current page number.
`X-Pagination-Limit`	Items per page (after the server applies any clamping).
`X-Pagination-Page-Count`	Total number of pages available — bounded by the `page` cap (max 20).
`X-Pagination-Item-Count`	Total number of items matching the request across all pages.

Stop on X-Pagination-Page-Count. When X-Pagination-Page equals X-Pagination-Page-Count, you’ve fetched the last accessible page. The Item-Count can exceed Page-Count × Limit if the underlying result set is larger than the 20-page cap allows — Page-Count is the practical ceiling.

A simple paginator

These snippets default to a conservative limit=50 that fits inside every paginated endpoint’s cap. Bump to 60 if you’re hitting a genre or premieres endpoint and want bigger pages.

async function* paginate(url, headers, limit = 50) {
  let page = 1;
  while (true) {
    const res = await fetch(`${url}?page=${page}&limit=${limit}`, { headers });
    yield await res.json();
    const totalPages = Number(res.headers.get('X-Pagination-Page-Count'));
    if (page >= totalPages) return;
    page++;
  }
}

import requests

def paginate(url, headers, limit=50):
    page = 1
    while True:
        res = requests.get(url, params={'page': page, 'limit': limit}, headers=headers)
        yield res.json()
        total_pages = int(res.headers.get('X-Pagination-Page-Count', '1'))
        if page >= total_pages:
            return
        page += 1

The hard page cap is 20. No matter how many results match, you can never fetch beyond page 20 — that’s 20 × max_limit = 1,200 items in the best case. If you need to walk a larger result set, narrow the query with the endpoint’s own filter parameters (genre, year, country, network, sort) rather than paging deeper.

Get started

Authentication

Conventions

Guides

API Debug

Resources

Per-endpoint defaults

Query parameters

Response headers

A simple paginator

​Per-endpoint defaults

​Query parameters

​Response headers

​A simple paginator

Per-endpoint defaults

Query parameters

Response headers

A simple paginator