Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api.simkl.org/llms.txt

Use this file to discover all available pages before exploring further.

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 familyDefault limitMax limitMax page
GET /search/{type} (text search)105020
GET /tv/genres/..., GET /anime/genres/..., GET /movies/genres/... (by genre)606020
GET /tv/premieres/{param}, GET /anime/premieres/{param}606020
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

ParameterTypeDescription
pageinteger (1–20)Which page to return. Defaults to 1.
limitinteger (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:
HeaderMeaning
X-Pagination-PageThe current page number.
X-Pagination-LimitItems per page (after the server applies any clamping).
X-Pagination-Page-CountTotal number of pages available — bounded by the page cap (max 20).
X-Pagination-Item-CountTotal 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++;
  }
}
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.