List sessions
curl --request GET \
--url https://agp.eu.hcompany.ai/api/v2/sessions \
--header 'Authorization: Bearer <token>'import requests
url = "https://agp.eu.hcompany.ai/api/v2/sessions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://agp.eu.hcompany.ai/api/v2/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://agp.eu.hcompany.ai/api/v2/sessions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://agp.eu.hcompany.ai/api/v2/sessions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"agent": {},
"status": "<string>",
"agent_view_url": {},
"first_message": {},
"created_at": "<string>",
"started_at": {},
"finished_at": {},
"last_activity_at": {},
"anonymized_at": {}
}Sessions
List sessions
Browse your sessions with filtering, sorting, and pagination.
GET
/
api
/
v2
/
sessions
List sessions
curl --request GET \
--url https://agp.eu.hcompany.ai/api/v2/sessions \
--header 'Authorization: Bearer <token>'import requests
url = "https://agp.eu.hcompany.ai/api/v2/sessions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://agp.eu.hcompany.ai/api/v2/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://agp.eu.hcompany.ai/api/v2/sessions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://agp.eu.hcompany.ai/api/v2/sessions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"agent": {},
"status": "<string>",
"agent_view_url": {},
"first_message": {},
"created_at": "<string>",
"started_at": {},
"finished_at": {},
"last_activity_at": {},
"anonymized_at": {}
}Lists the sessions visible to you, newest first by default.
Returns a page envelope whose
items are session summaries (fields below). Read a full session with Retrieve.
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
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 org), organization (everyone’s sessions in the org), 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
string
Session UUID.
string | null
Name of the agent that ran the session.
string | null
The session’s Agent View page.
object | null
The first user message:
type, message, images, files, caller_id.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.
null for sessions that predate the field.string | null
When the session’s PII text and screenshots were irreversibly anonymized.
null if not anonymized.Examples
List your recent sessions
hai sessions list --size 5
curl "https://agp.eu.hcompany.ai/api/v2/sessions?size=5" \
-H "Authorization: Bearer $HAI_API_KEY"
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);
}
Response
{
"items": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"agent": "h/web-surfer-flash",
"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",
"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
}
Filter by status and agent
curl "https://agp.eu.hcompany.ai/api/v2/sessions?status=running&agent=web-price-finder" \
-H "Authorization: Bearer $HAI_API_KEY"
page = client.sessions.list_sessions(status=["running"], agent=["web-price-finder"])
const page = await client.sessions.listSessions({
status: ["running"],
agent: ["web-price-finder"],
});
List all sessions in a group
curl "https://agp.eu.hcompany.ai/api/v2/sessions?group_id=trip-planning-001" \
-H "Authorization: Bearer $HAI_API_KEY"
page = client.sessions.list_sessions(group_id="trip-planning-001")
const page = await client.sessions.listSessions({ groupId: "trip-planning-001" });
Find the subagents a session spawned
Pass a multi-agent parent’s ID asparent_session_id to list its child sessions, each labeled with the agent that ran it. Recurse on a child’s ID for deeper trees.
curl "https://agp.eu.hcompany.ai/api/v2/sessions?parent_session_id=$PARENT_SESSION_ID" \
-H "Authorization: Bearer $HAI_API_KEY"
page = client.sessions.list_sessions(parent_session_id=parent_session_id)
const page = await client.sessions.listSessions({ parentSessionId });
Response
{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
"agent": "fast-searcher",
"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
}
Was this page helpful?