> ## 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.

# Pagination

> How paginated endpoints work — request size, page numbers, and the response headers Simkl returns.

Some Simkl endpoints return many items and are paginated. Paginated endpoints are marked with **📄 Pagination** in the [API Reference](/api-reference/introduction).

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}`](/api-reference/simkl/search-by-text) *(text search)*                                                                                                                                   | **10**          | 50          | 20         |
| [`GET /tv/genres/...`](/api-reference/simkl/get-tv-genres), [`GET /anime/genres/...`](/api-reference/simkl/get-anime-genres), [`GET /movies/genres/...`](/api-reference/simkl/get-movies-genres) *(by genre)* | **60**          | 60          | 20         |
| [`GET /tv/premieres/{param}`](/api-reference/simkl/get-tv-premieres), [`GET /anime/premieres/{param}`](/api-reference/simkl/get-anime-premieres)                                                              | **60**          | 60          | 20         |

`page` defaults to `1` on every paginated endpoint.

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

## 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. |

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
# 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.          |

<Tip>
  **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.
</Tip>

## 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.

<CodeGroup>
  ```js Node theme={"theme":{"light":"github-light","dark":"vesper"}}
  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++;
    }
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vesper"}}
  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
  ```
</CodeGroup>

<Warning>
  **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.
</Warning>