List sessions

GET

api

sessions

holo sessions list --size 5

from hai_agents import Client

client = Client()

page = client.sessions.list_sessions(size=5)
for summary in page.items:
    print(summary.id, summary.status)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const page = await client.sessions.listSessions({ size: 5 });
for (const summary of page.items) {
  console.log(summary.id, summary.status);
}

curl "https://agp.eu.hcompany.ai/api/v2/sessions?size=5" \
  -H "Authorization: Bearer $HAI_API_KEY"

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent": "h/web-surfer-flash",
      "agent_revision": 4,
      "status": "completed",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_message": {"type": "user_message", "message": "Open Hacker News and list the top 3 stories with their URLs.", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:30:00Z",
      "started_at": "2026-05-07T14:30:02Z",
      "finished_at": "2026-05-07T14:31:15Z",
      "last_activity_at": "2026-05-07T14:31:15Z",
      "anonymized_at": null
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "agent": "web-price-finder",
      "agent_revision": null,
      "status": "running",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "first_message": {"type": "user_message", "message": "Find direct flights CDG to NRT", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:25:00Z",
      "started_at": "2026-05-07T14:25:01Z",
      "finished_at": null,
      "last_activity_at": "2026-05-07T14:29:58Z",
      "anonymized_at": null
    }
  ],
  "page": 1,
  "total": 47
}

Query parameters

string[]

Filter by session status. Repeatable. Values: queued, pending, running, paused, idle, awaiting_tool_results, completed, failed, timed_out, interrupted.

string[]

Filter by agent identifier. Repeatable. Example: web-price-finder.

string

Only sessions tagged with this group.

string

Only child sessions of this parent.

string

Only sessions created by this schedule.

string

Case-insensitive match on the session’s first message or answer.

string

Only sessions created before this ISO 8601 timestamp.

string

Only sessions created after this ISO 8601 timestamp.

string

Only sessions that finished before this ISO 8601 timestamp.

string

Only sessions that finished after this ISO 8601 timestamp.

string

default:"me-in-organization"

Access scope: me (your sessions anywhere), me-in-organization (your sessions in the current organization), organization (everyone’s sessions in the organization), or me-or-organization.

integer

default:"1"

Page number (1-based).

integer

default:"10"

Items per page. Maximum: 100.

string

default:"-created_at"

Sort order. Options: created_at, -created_at.

Response

200 with a page envelope whose items are session summaries with these fields. Read a full session with Retrieve.

string

Session UUID.

string | null

Name of the agent that ran the session.

integer | null

The catalog agent’s revision the session ran. null for inline agents.

string

Current status.

string | null

The session’s Agent View page.

object | null

The first user message, as sent in messages.

string

string[]

object[]

string

ISO 8601 creation time.

string | null

When the agent started.

string | null

When the session reached a terminal state.

string | null

When the session’s latest event was ingested (agent steps, status changes, user messages), to spot which live sessions are moving.

string | null

When the session’s PII text and screenshots were irreversibly anonymized. null if not anonymized.

holo sessions list --size 5

from hai_agents import Client

client = Client()

page = client.sessions.list_sessions(size=5)
for summary in page.items:
    print(summary.id, summary.status)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const page = await client.sessions.listSessions({ size: 5 });
for (const summary of page.items) {
  console.log(summary.id, summary.status);
}

curl "https://agp.eu.hcompany.ai/api/v2/sessions?size=5" \
  -H "Authorization: Bearer $HAI_API_KEY"

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent": "h/web-surfer-flash",
      "agent_revision": 4,
      "status": "completed",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_message": {"type": "user_message", "message": "Open Hacker News and list the top 3 stories with their URLs.", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:30:00Z",
      "started_at": "2026-05-07T14:30:02Z",
      "finished_at": "2026-05-07T14:31:15Z",
      "last_activity_at": "2026-05-07T14:31:15Z",
      "anonymized_at": null
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "agent": "web-price-finder",
      "agent_revision": null,
      "status": "running",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "first_message": {"type": "user_message", "message": "Find direct flights CDG to NRT", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:25:00Z",
      "started_at": "2026-05-07T14:25:01Z",
      "finished_at": null,
      "last_activity_at": "2026-05-07T14:29:58Z",
      "anonymized_at": null
    }
  ],
  "page": 1,
  "total": 47
}

More examples

Filter by status and agent

page = client.sessions.list_sessions(status=["running"], agent=["web-price-finder"])

const page = await client.sessions.listSessions({
  status: ["running"],
  agent: ["web-price-finder"],
});

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

List all sessions in a group

page = client.sessions.list_sessions(group_id="trip-planning-001")

const page = await client.sessions.listSessions({ groupId: "trip-planning-001" });

curl "https://agp.eu.hcompany.ai/api/v2/sessions?group_id=trip-planning-001" \
  -H "Authorization: Bearer $HAI_API_KEY"

Find the subagents a session spawned

Pass a manager session’s ID as parent_session_id to list its child sessions, each labeled with the agent that ran it. Recurse on a child’s ID for deeper trees.

page = client.sessions.list_sessions(parent_session_id=parent_session_id)

const page = await client.sessions.listSessions({ parentSessionId });

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

Response

{
  "items": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "agent": "fast-searcher",
      "agent_revision": null,
      "status": "completed",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "first_message": {"type": "user_message", "message": "Search EV market-share figures for 2025", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:30:05Z",
      "started_at": "2026-05-07T14:30:06Z",
      "finished_at": "2026-05-07T14:30:41Z",
      "last_activity_at": "2026-05-07T14:30:41Z",
      "anonymized_at": null
    }
  ],
  "page": 1,
  "total": 1
}

holo sessions list --size 5

from hai_agents import Client

client = Client()

page = client.sessions.list_sessions(size=5)
for summary in page.items:
    print(summary.id, summary.status)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const page = await client.sessions.listSessions({ size: 5 });
for (const summary of page.items) {
  console.log(summary.id, summary.status);
}

curl "https://agp.eu.hcompany.ai/api/v2/sessions?size=5" \
  -H "Authorization: Bearer $HAI_API_KEY"

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent": "h/web-surfer-flash",
      "agent_revision": 4,
      "status": "completed",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_message": {"type": "user_message", "message": "Open Hacker News and list the top 3 stories with their URLs.", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:30:00Z",
      "started_at": "2026-05-07T14:30:02Z",
      "finished_at": "2026-05-07T14:31:15Z",
      "last_activity_at": "2026-05-07T14:31:15Z",
      "anonymized_at": null
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "agent": "web-price-finder",
      "agent_revision": null,
      "status": "running",
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "first_message": {"type": "user_message", "message": "Find direct flights CDG to NRT", "images": [], "files": [], "caller_id": "user"},
      "created_at": "2026-05-07T14:25:00Z",
      "started_at": "2026-05-07T14:25:01Z",
      "finished_at": null,
      "last_activity_at": "2026-05-07T14:29:58Z",
      "anonymized_at": null
    }
  ],
  "page": 1,
  "total": 47
}

Build an agent

Environments

Run sessions

Tools and integrations

Production

API reference

Query parameters

Response

More examples

Filter by status and agent

List all sessions in a group

Find the subagents a session spawned

​Query parameters

​Response

​More examples

​Filter by status and agent

​List all sessions in a group

​Find the subagents a session spawned

Query parameters

Response

More examples

Filter by status and agent

List all sessions in a group

Find the subagents a session spawned