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": [
    {}
  ]
}

GET

api

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 answer, long-poll changes instead. Returns a status object with the fields below.

Path parameters

string

required

The session ID.

Response

status

string

required

Current session state: queued, pending, running, paused, idle, awaiting_tool_results, completed, failed, timed_out, or interrupted.

error

string

Short, stable error message if the session failed or timed out. null otherwise. Branch on error_code, not on this text.

error_code

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.

outcome

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.

steps

integer

Number of steps the agent has taken, where each step is one decide-and-act cycle.

usage_per_model

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
  }
]

subagent_session_ids

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));
}

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.

Retrieve Changes

Agents

Environments

Sessions

Skills

Vaults

Browser Profiles

Webhooks

Schedules

Get session status

Path parameters

Response

Examples

Polling pattern

​Path parameters

​Response

​Examples

​Polling pattern

Path parameters

Response

Examples

Polling pattern