Get session changes

Long-poll for new events and the answer.

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

Python

from hai_agents import Client

client = Client()

changes = client.sessions.get_session_changes(
    session_id,
    from_index=0,
    wait_for_seconds=25,
)

200

{
  "status": "running",
  "started_at": "2026-05-07T14:30:02Z",
  "finished_at": null,
  "error": null,
  "error_code": null,
  "answer": null,
  "outcome": null,
  "metrics": {
    "steps": 2,
    "total_cost": 0.0093874,
    "input_cost": 0.0084664,
    "output_cost": 0.000921,
    "reasoning_cost": 0.0,
    "cost_per_model": [
      {
        "name": "holo4-27b",
        "input_tokens": 21166,
        "cached_tokens": 0,
        "output_tokens": 307,
        "reasoning_tokens": 0,
        "input_cost": 0.0084664,
        "output_cost": 0.000921,
        "reasoning_cost": 0.0,
        "total_cost": 0.0093874
      }
    ]
  },
  "new_events": [
    { "type": "AgentEvent", "data": { "...": "..." }, "timestamp": "2026-05-07T14:30:05Z" }
  ],
  "first_index": 0,
  "pending_tool_calls": []
}

Behavior

Works without a key on shared sessions.

Polling rules

Poll /changes until status is terminal and a poll returns no events.

• The server holds the request open until something new arrives or wait_for_seconds expires.
• Each call returns only what is new since from_index. 204 means no new events yet.
• status can read completed before you reach the page with the final events and the answer, so a terminal status alone doesn’t end the loop.
• For a finished session, read latest_answer instead, or let the SDK helper run the loop.

Path parameters

id · string · required

The session ID.

Query parameters

from_index · integer · default: "0"

Event index to start from. Pass the next unread index to resume where you left off.

limit · integer

Maximum number of events to return. Minimum 0.

include_events · boolean · default: "true"

Whether to include event details in the response.

wait_for_seconds · integer · default: "0"

How long the server holds the request waiting for changes, 0 to 25 seconds. 0 returns immediately, and 20 to 25 gives efficient long polling.

Response

200 with the changes object, or 204 No Content if no new events arrive within the wait.

status · string

Current session status.

started_at · string | null

When the agent started executing.

finished_at · string | null

When the session reached a terminal state.

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

Failure category when 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.

answer · string | object | null

The agent’s final result once produced: a string, or an object matching the agent’s answer_format. It can arrive after status turns terminal (Polling rules). Mirrored on the session’s latest_answer.

metrics · object

Usage and cost so far. Costs are in USD and null when a model’s price is unavailable, so null-check before summing.

steps · integer

total_cost · number | null

input_cost · number | null

output_cost · number | null

reasoning_cost · number | null

cost_per_model · object[]

Per-model usage and cost.

name · string

input_tokens · integer

cached_tokens · integer

output_tokens · integer

reasoning_tokens · integer

input_cost · number | null

output_cost · number | null

reasoning_cost · number | null

total_cost · number | null

new_events · object[]

Events since from_index, each an Event object (type, data, timestamp).

first_index · integer | null

Index of new_events[0]. Your next from_index is first_index plus the number of new_events. It equals from_index in the cloud. A local runtime session keeps a window of recent events, so it can be higher there when older events were dropped.

pending_tool_calls · object[]

The custom tool calls the agent is waiting on, as on status. 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()

changes = client.sessions.get_session_changes(
    session_id,
    from_index=0,
    wait_for_seconds=25,
)

200

{
  "status": "running",
  "started_at": "2026-05-07T14:30:02Z",
  "finished_at": null,
  "error": null,
  "error_code": null,
  "answer": null,
  "outcome": null,
  "metrics": {
    "steps": 2,
    "total_cost": 0.0093874,
    "input_cost": 0.0084664,
    "output_cost": 0.000921,
    "reasoning_cost": 0.0,
    "cost_per_model": [
      {
        "name": "holo4-27b",
        "input_tokens": 21166,
        "cached_tokens": 0,
        "output_tokens": 307,
        "reasoning_tokens": 0,
        "input_cost": 0.0084664,
        "output_cost": 0.000921,
        "reasoning_cost": 0.0,
        "total_cost": 0.0093874
      }
    ]
  },
  "new_events": [
    { "type": "AgentEvent", "data": { "...": "..." }, "timestamp": "2026-05-07T14:30:05Z" }
  ],
  "first_index": 0,
  "pending_tool_calls": []
}

Long-polling pattern

The SDK helper runs the polling loop for you: it advances from_index, handles 204 responses, and returns once the session is terminal or idle and every event is read.

Python

from hai_agents import wait_for_session

result = wait_for_session(client, session_id, wait_for_seconds=25)

for event in result.events:
    print(event.type)
print(result.status, result.answer)

# client.run_session(...) creates the session and runs this loop in one call.

Errors

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