Skip to main content
List endpoints return paginated results. The API uses page-based pagination with consistent parameters across all resources.

​
Pagination parameters

ParameterTypeDefaultConstraints
pageinteger1>= 1
sizeinteger101–1000
sortlist[string]variesEndpoint-specific fields, prefix - for descending
The session event stream (GET /sessions/{id}/events) is the one exception: it defaults size to 50 and caps it at 200.

​
Response shape

Every paginated response has the same envelope: 
{
  "items": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "..." : "..." },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "..." : "..." }
  ],
  "page": 1,
  "total": 142
}
FieldTypeDescription
itemsarrayThe resources on this page.
pageintegerCurrent page number.
totalintegerTotal number of matching resources across all pages.
Responses don’t echo back the size you sent, so track it yourself. There are more pages while page * size < total.

​
Example: iterate through all sessions

import requests

page = 1
all_sessions = []

while True:
    response = requests.get(
        "https://agp.eu.hcompany.ai/api/v2/sessions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={"page": page, "size": 50},
    ).json()

    all_sessions.extend(response["items"])

    if page * 50 >= response["total"]:
        break
    page += 1

print(f"Fetched {len(all_sessions)} sessions")

​
Sorting

List endpoints support sorting via the sort parameter. Prefix with - for descending order.

​
Sessions

Sort valueDescription
created_atOldest first.
-created_atNewest first (default).

​
Agents

Sort valueDescription
created_at / -created_atBy creation date.
agent_name / -agent_nameAlphabetical by name.

​
Skills

Sort valueDescription
created_at / -created_atBy creation date.
name / -nameAlphabetical by name.
# Get the 10 most recent sessions
curl "https://agp.eu.hcompany.ai/api/v2/sessions?sort=-created_at&size=10" \
  -H "Authorization: Bearer $H_API_KEY"

​
Filtering sessions

The GET /api/v2/sessions endpoint supports several filters that can be combined:
FilterTypeDescription
status[]string (multi-value)Filter by session status (e.g., running, completed).
agent[]string (multi-value)Filter by agent identifier (e.g., web-price-finder).
group_idstringFilter by group: useful for multi-session workflows.
parent_session_idstringFind child sessions of a parent.
ownerstringAccess scope. Default: me-in-organization.

​
Example: find all running sessions for a specific agent

curl "https://agp.eu.hcompany.ai/api/v2/sessions?status=running&agent=web-price-finder" \
  -H "Authorization: Bearer $H_API_KEY"

​
Example: find child sessions of a parent

curl "https://agp.eu.hcompany.ai/api/v2/sessions?parent_session_id=$SESSION_ID" \
  -H "Authorization: Bearer $H_API_KEY"

​
Filtering skills

The GET /api/v2/skills endpoint supports:
FilterTypeDescription
namestringName prefix filter.