Skip to main content
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>'
{
  "status": "<string>",
  "error": "<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 SessionStatus object.

​
Path parameters

​
id
string
required
The session ID.

​
Response

​
status
string
required
Current session state: pending, running, paused, idle, awaiting_tool_results, completed, failed, timed_out, or interrupted.
​
error
string
Error message if the session failed. null otherwise.
​
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"
Response
{
  "status": "running",
  "error": 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 requests
import time

API = "https://agp.eu.hcompany.ai/api/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

while True:
    status = requests.get(f"{API}/sessions/{session_id}/status", headers=HEADERS).json()

    match status["status"]:
        case "completed":
            # status carries no answer; read the snapshot off the session
            session = requests.get(f"{API}/sessions/{session_id}", headers=HEADERS).json()
            print(f"Done in {status['steps']} steps: {session['latest_answer']}")
            break
        case "failed" | "timed_out" | "interrupted":
            print(f"Session ended: {status['status']}")
            if status.get("error"):
                print(f"  Error: {status['error']}")
            break
        case _:
            print(f"  {status['status']}... ({status['steps']} steps)")
            time.sleep(3)
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.