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

# Pagination and filtering

> Build complete, efficient, and restartable reads.

List endpoints use offset pagination. They default to 50 records and accept a
maximum `limit` of 200.

```json theme={null}
{
  "pagination": {
    "total": 248,
    "limit": 200,
    "offset": 0
  }
}
```

Request the next page while `offset + limit < total`. The maximum accepted
offset is 1,000,000.

## Read every page

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

  base_url = "https://api-us.hihobbes.com/api/v1/sessions"
  headers = {"Authorization": f"Bearer {os.environ['HOBBES_API_KEY']}"}
  offset = 0

  while True:
      response = requests.get(
          base_url,
          headers=headers,
          params={"limit": 200, "offset": offset},
          timeout=30,
      )
      response.raise_for_status()
      payload = response.json()

      for session in payload["sessions"]:
          process(session)

      page = payload["pagination"]
      offset += page["limit"]
      if offset >= page["total"]:
          break
  ```

  ```typescript TypeScript theme={null}
  const endpoint = "https://api-us.hihobbes.com/api/v1/sessions";
  let offset = 0;

  while (true) {
    const url = new URL(endpoint);
    url.searchParams.set("limit", "200");
    url.searchParams.set("offset", String(offset));

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.HOBBES_API_KEY}` },
    });
    if (!response.ok) throw new Error(await response.text());

    const payload = await response.json();
    for (const session of payload.sessions) await processSession(session);

    offset += payload.pagination.limit;
    if (offset >= payload.pagination.total) break;
  }
  ```
</CodeGroup>

## Filters

Session and people filters can be combined. Status filters accept comma-separated
values, such as `buying_intent=high,medium`.

| Filter                 | Sessions | People | Behavior                                              |
| ---------------------- | -------- | ------ | ----------------------------------------------------- |
| `date_from`, `date_to` | Yes      | Yes    | Session start time or person last-seen time, ISO 8601 |
| `qualification_status` | Yes      | Yes    | `qualified`, `unqualified`, `unknown`                 |
| `buying_intent`        | Yes      | Yes    | `high`, `medium`, `low`, `none`                       |
| `booked_status`        | Yes      | No     | `booked`, `not_booked`                                |
| `search`               | Email    | Email  | Case-insensitive partial match                        |

Account `search` performs a partial domain match. Metrics use a trailing `days`
window instead of date boundaries.

<Note>
  Offset pagination is stable enough for bounded backfills, but records can be
  added while a long export runs. For recurring exports, use an overlapping
  `date_from` watermark and upsert by stable resource id.
</Note>