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

# Pagination

> All list endpoints use the same page/limit pattern. Response includes total counts so you can build paginated UIs.

List endpoints (`GET /agents`, `GET /conversations`, `GET /clients`, etc.) use a single, consistent pagination shape: **page + limit**.

## Request

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents?page=2&limit=50" \
  -H "X-Api-Key: $GENNIA_API_KEY"
```

| Parameter | Type        | Default | Max   |
| --------- | ----------- | ------- | ----- |
| `page`    | integer ≥ 1 | `1`     | —     |
| `limit`   | integer     | `20`    | `100` |

Invalid pagination (page \< 1, limit > 100) returns `400 VALIDATION_ERROR`.

## Response envelope

Every paginated response wraps the items in the same shape:

```json theme={null}
{
  "items": [
    { "publicId": "...", "name": "..." },
    ...
  ],
  "page": 2,
  "limit": 50,
  "total": 123,
  "totalPages": 3
}
```

| Field        | Meaning                               |
| ------------ | ------------------------------------- |
| `items`      | The page's results.                   |
| `page`       | Echo of the requested page (1-based). |
| `limit`      | Echo of the requested limit.          |
| `total`      | Total result count across all pages.  |
| `totalPages` | `ceil(total / limit)`.                |

## Iterating through all pages

```bash theme={null}
page=1
while :; do
  resp=$(curl -s "https://api.gennia.ai/public/api/v1/agents?page=$page&limit=100" \
    -H "X-Api-Key: $GENNIA_API_KEY")
  echo "$resp" | jq -c '.items[]'
  total_pages=$(echo "$resp" | jq -r '.totalPages')
  [ "$page" -ge "$total_pages" ] && break
  page=$((page + 1))
done
```

<Tip>
  When you don't know the total upfront, you can also stop as soon as `items` comes back empty. But always check `totalPages` if you need consistent end-of-data behavior.
</Tip>

## Filters

Most list endpoints accept additional query parameters to narrow the result set:

| Endpoint                 | Typical filters                  |
| ------------------------ | -------------------------------- |
| `GET /agents`            | `includeArchived`                |
| `GET /clients`           | `status`, `q` (free-text search) |
| `GET /conversations`     | `status`, `agentPublicId`        |
| `GET /knowledge-sources` | `status`, `search`               |

Refer to the individual endpoint pages in the reference for the full filter list.

## Stable ordering

Results are **ordered by `createdAt` descending** (newest first) unless the endpoint documentation specifies otherwise. This means new resources can appear on the first page during iteration — if you need a stable snapshot, capture it once and store the IDs.