Get session status

Get a session’s state, step count, and token usage.

GET /api/v2/sessions/{id}/status

Python

from hai_agents import Client

client = Client()

status = client.sessions.get_session_status(session_id)
print(status.status, status.steps)

200

{
  "status": "running",
  "error": null,
  "error_code": null,
  "outcome": null,
  "steps": 7,
  "usage_per_model": [
    {
      "name": "holo4-27b",
      "input_tokens": 12400,
      "cached_tokens": 9800,
      "output_tokens": 890,
      "reasoning_tokens": 0
    }
  ],
  "subagent_session_ids": [],
  "pending_tool_calls": []
}

Behavior

The status never carries the answer. To get it, follow the polling rules. Works without a key on shared sessions.

Path parameters

id · string · required

The session ID.

Response

200 with the status object.

status · string · required

Current state: queued, pending, running, paused, idle, awaiting_tool_results, completed, failed, timed_out, or interrupted, as in the lifecycle.

error · string | null

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

error_code · string | null

Machine-readable failure category if the session failed or timed out: environment_error, no_answer, answer_validation, timeout, insufficient_credit, or internal.

outcome · string | null

The agent’s self-assessed outcome, reported with its final answer: success, partial, infeasible, or blocked. null until reported.

steps · integer

Steps taken so far, where each step is one decide-and-act cycle.

usage_per_model · object[]

Per-model token usage. Empty until the agent calls a model.

name · string

input_tokens · integer

cached_tokens · integer

Input served from the prompt cache, billed at a discount.

output_tokens · integer

reasoning_tokens · integer

subagent_session_ids · string[]

IDs of the child sessions this session spawned. List them with their agent labels via GET /sessions?parent_session_id={id}.

pending_tool_calls · object[]

The custom tool calls the agent is waiting on. Echo each one back as tool_req when you post its result. Empty unless the status is awaiting_tool_results, or paused while calls are pending.

tool_name · string

args · object

id · string | null

Python

from hai_agents import Client

client = Client()

status = client.sessions.get_session_status(session_id)
print(status.status, status.steps)

200

{
  "status": "running",
  "error": null,
  "error_code": null,
  "outcome": null,
  "steps": 7,
  "usage_per_model": [
    {
      "name": "holo4-27b",
      "input_tokens": 12400,
      "cached_tokens": 9800,
      "output_tokens": 890,
      "reasoning_tokens": 0
    }
  ],
  "subagent_session_ids": [],
  "pending_tool_calls": []
}

Errors

Status	Cause
404	Not found, or not in your organization.