List endpoints (GET /agents, GET /conversations, GET /clients, etc.) use a single, consistent pagination shape: page + limit.
Request
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 |
400 VALIDATION_ERROR.
Response envelope
Every paginated response wraps the items in the same shape:
{
"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
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
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.
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 |
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. 
