Get session status
curl --request GET \
--url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/status \
--header 'Authorization: Bearer <token>'import requests
url = "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/status"
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/{id}/status', 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/{id}/status",
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/{id}/status"
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/{id}/status")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/sessions/{id}/status")
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{
"status": "<string>",
"error": "<string>",
"error_code": "<string>",
"outcome": "<string>",
"steps": 123,
"usage_per_model": [
{}
],
"subagent_session_ids": [
{}
]
}Sessions
Get session status
Lightweight polling endpoint for session progress.
GET
/
api
/
v2
/
sessions
/
{id}
/
status
Get session status
curl --request GET \
--url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/status \
--header 'Authorization: Bearer <token>'import requests
url = "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/status"
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/{id}/status', 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/{id}/status",
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/{id}/status"
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/{id}/status")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/sessions/{id}/status")
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{
"status": "<string>",
"error": "<string>",
"error_code": "<string>",
"outcome": "<string>",
"steps": 123,
"usage_per_model": [
{}
],
"subagent_session_ids": [
{}
]
}Returns only the live status of a session: current state, step count, token usage, and subagent IDs. It’s the cheapest call for a quick liveness check. To follow a run and read its
For the polling interval, 2 to 5 seconds works well for most use cases. For longer tasks (10+ minutes), back off to 10 to 15 seconds to reduce API calls.
answer, long-poll changes instead.
Returns a status object with the fields below.
Path parameters
string
required
The session ID.
Response
string
required
Current session state:
queued, pending, running, paused, idle, awaiting_tool_results, completed, failed, timed_out, or interrupted.string
Short, stable error message if the session failed or timed out.
null otherwise. Branch on error_code, not on this text.string
Machine-readable failure category if the session failed or timed out:
environment_error, no_answer, answer_validation, timeout, or internal. null otherwise. See Read how the run ended.string
The agent’s self-assessed task outcome, reported with its final answer:
success, partial, infeasible, or blocked. null until reported. See Read how the run ended.integer
Number of steps the agent has taken, where each step is one decide-and-act cycle.
array
Per-model token usage. Each entry is an object with
name, input_tokens, output_tokens, and reasoning_tokens. Empty array until the agent calls a model."usage_per_model": [
{
"name": "holo3-1-35b-a3b",
"input_tokens": 12400,
"output_tokens": 890,
"reasoning_tokens": 0
}
]
array
IDs of the child sessions this session spawned, empty if it ran no subagents. Pull the full roster, each child labeled with its
agent, with GET /sessions?parent_session_id={id}.Examples
curl https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/status \
-H "Authorization: Bearer $HAI_API_KEY"
from hai_agents import Client
client = Client()
status = client.sessions.get_session_status(session_id)
print(status.status, status.steps)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const status = await client.sessions.getSessionStatus({ id: sessionId });
console.log(status.status, status.steps);
Response
{
"status": "running",
"error": null,
"error_code": null,
"outcome": null,
"steps": 7,
"usage_per_model": [
{
"name": "holo3-1-35b-a3b",
"input_tokens": 12400,
"output_tokens": 890,
"reasoning_tokens": 0
}
],
"subagent_session_ids": []
}
Polling pattern
A typical polling loop checks status every few seconds and branches on the result:import time
while True:
status = client.sessions.get_session_status(session_id)
match status.status:
case "completed":
# status carries no answer; read the snapshot off the session
session = client.sessions.get_session(session_id)
print(f"Done in {status.steps} steps: {session.latest_answer}")
break
case "failed" | "timed_out" | "interrupted":
print(f"Session ended: {status.status}")
if status.error:
print(f" Error: {status.error}")
break
case _:
print(f" {status.status}... ({status.steps} steps)")
time.sleep(3)
while (true) {
const status = await client.sessions.getSessionStatus({ id: sessionId });
if (status.status === "completed") {
// status carries no answer; read the snapshot off the session
const session = await client.sessions.getSession({ id: sessionId });
console.log(`Done in ${status.steps} steps: ${session.latestAnswer}`);
break;
}
if (["failed", "timed_out", "interrupted"].includes(status.status)) {
console.log(`Session ended: ${status.status}`, status.error ?? "");
break;
}
console.log(` ${status.status}... (${status.steps} steps)`);
await new Promise((resolve) => setTimeout(resolve, 3000));
}
Last modified on September 11, 2026
Was this page helpful?