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

# Pagination

> Navigate through large result sets

List endpoints return paginated results using cursor-based pagination.

## Response format

Paginated responses include a `pagination` object alongside the `data` array:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    { "id": "abc-123", "title": "..." },
    { "id": "def-456", "title": "..." }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6ImRlZi00NTYifQ==",
    "total_count": 142
  }
}
```

| Field         | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `has_more`    | `true` if more results exist beyond this page                                                   |
| `next_cursor` | Opaque cursor to pass as `cursor` query parameter for the next page. `null` if no more results. |
| `total_count` | Total number of matching records                                                                |

## Query parameters

| Parameter | Default | Max | Description                                                |
| --------- | ------- | --- | ---------------------------------------------------------- |
| `limit`   | 25      | 100 | Number of results per page                                 |
| `cursor`  | —       | —   | Cursor from a previous response's `pagination.next_cursor` |

<Warning>
  Cursors are opaque strings. **Do not modify, decode, or construct cursors manually** — they are subject to change without notice. Always use the `next_cursor` value exactly as returned.
</Warning>

## Paginating through results

<Steps>
  <Step title="Fetch the first page">
    Make a request with your desired `limit` and no `cursor` parameter.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl "https://api.app.hrizn.io/v1/public/ideaclouds?limit=10" \
      -H "X-API-Key: hzk_your_key_here"
    ```
  </Step>

  <Step title="Check for more results">
    Inspect `pagination.has_more` in the response. If `true`, there are more pages.
  </Step>

  <Step title="Fetch subsequent pages">
    Pass the `next_cursor` value as the `cursor` query parameter:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl "https://api.app.hrizn.io/v1/public/ideaclouds?limit=10&cursor=eyJpZCI6ImRlZi00NTYifQ==" \
      -H "X-API-Key: hzk_your_key_here"
    ```
  </Step>

  <Step title="Repeat until done">
    Continue fetching pages until `has_more` is `false` or `next_cursor` is `null`.
  </Step>
</Steps>

## Full iteration example

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  async function fetchAll(baseUrl: string, apiKey: string) {
    const results = [];
    let cursor: string | null = null;

    do {
      const url = new URL(baseUrl);
      url.searchParams.set("limit", "100");
      if (cursor) url.searchParams.set("cursor", cursor);

      const res = await fetch(url, {
        headers: { "X-API-Key": apiKey },
      });
      const json = await res.json();

      results.push(...json.data);
      cursor = json.pagination.next_cursor;
    } while (cursor);

    return results;
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  def fetch_all(base_url: str, api_key: str) -> list:
      results = []
      cursor = None

      while True:
          params = {"limit": 100}
          if cursor:
              params["cursor"] = cursor

          response = requests.get(
              base_url,
              headers={"X-API-Key": api_key},
              params=params,
          )
          json = response.json()

          results.extend(json["data"])
          cursor = json["pagination"]["next_cursor"]
          if not cursor:
              break

      return results
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  function fetchAll(string $baseUrl, string $apiKey): array {
      $results = [];
      $cursor = null;

      do {
          $url = $baseUrl . "?limit=100";
          if ($cursor) $url .= "&cursor=" . urlencode($cursor);

          $ch = curl_init($url);
          curl_setopt_array($ch, [
              CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
              CURLOPT_RETURNTRANSFER => true,
          ]);
          $json = json_decode(curl_exec($ch), true);

          $results = array_merge($results, $json["data"]);
          $cursor = $json["pagination"]["next_cursor"];
      } while ($cursor);

      return $results;
  }
  ```
</CodeGroup>