> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routeur.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Offsets for ranked lists, cursors for long ones.

Lists that are ranked or searched page by **offset**; lists that can be long and change underneath you page by **cursor**. Everything else takes a `limit` and returns one page.

| Endpoint                                 | Pages by | Next page                                                      |
| ---------------------------------------- | -------- | -------------------------------------------------------------- |
| `GET /v1/events`                         | `offset` | Add `limit` to `offset` until a page comes back short.         |
| `GET /v1/search`                         | `offset` | Pass `next_offset` as `offset`. Search goes up to 300 results. |
| `GET /v1/markets/{venue}/{id}/relations` | `offset` | Add `limit` to `offset`.                                       |
| `GET /v1/cross-venue`                    | `offset` | Add `limit` to `offset`.                                       |
| `GET /v1/markets`                        | `cursor` | Pass `next_cursor` as `cursor`.                                |
| `GET /v1/markets/{venue}/{id}/trades`    | `cursor` | Pass `next_cursor` as `cursor`.                                |

## Cursors

A response carries `next_cursor` when more results exist. Pass it back unchanged; cursors are opaque and their format may change.

<CodeGroup>
  ```python Python theme={null}
  import os
  import requests

  session = requests.Session()
  session.headers["X-API-Key"] = os.environ["ROUTEUR_API_KEY"]

  def all_markets(q):
      params = {"q": q, "limit": 100}
      while True:
          page = session.get("https://api.routeur.app/v1/markets", params=params, timeout=20).json()
          yield from page["data"]
          if not page.get("next_cursor"):
              return
          params["cursor"] = page["next_cursor"]

  for market in all_markets("bitcoin"):
      print(market["venue"], market["id"], market["title"])
  ```

  ```typescript TypeScript theme={null}
  const headers = { 'X-API-Key': process.env.ROUTEUR_API_KEY! };

  async function* allMarkets(q: string) {
    const params = new URLSearchParams({ q, limit: '100' });
    while (true) {
      const res = await fetch(`https://api.routeur.app/v1/markets?${params}`, { headers });
      const page = await res.json();
      yield* page.data;
      if (!page.next_cursor) return;
      params.set('cursor', page.next_cursor);
    }
  }

  for await (const market of allMarkets('bitcoin')) {
    console.log(market.venue, market.id, market.title);
  }
  ```
</CodeGroup>

<Note>
  Graph-derived lists read from the latest finished graph run, named in `graph_run`. If a new run finishes while you page through an offset list, later pages come from the new run; compare `graph_run` across pages when that matters.
</Note>