Get session changes

Long-poll a session for new events, status, and the final answer since an event index, with the polling rules and the SDK wait helper.

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

Get session changes

cURL

curl --request GET \
  --url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/changes \
  --header 'Authorization: Bearer <token>'

Returns a stream of changes (events, status transitions, agent actions) that have occurred since your last request. Uses long polling: the server holds the connection open until new changes are available or the timeout expires.

Returns 200 with the response below, or 204 No Content if no new events arrive within the wait period.

Polling rules

changes is a delta: each call returns only what is new since from_index.

• The answer rides the page that delivers the final events. status can already read completed while those events sit unread on a later page, so keep advancing from_index until the session is terminal and a poll returns no further events.
• 204 No Content means no new events yet, not no answer.
• status never carries the answer.

To skip the loop and read a finished run’s result, use latest_answer: it needs no cursor and never goes stale. The SDK helper drains the loop for you.

---

Path parameters

id · string · required

The session ID.

---

Query parameters

from_index · integer · default: "0"

Event index to start from. Use this to resume from where you left off.

limit · integer

Maximum number of events to return.

include_events · boolean · default: "true"

Whether to include event details in the response.

wait_for_seconds · integer · default: "0"

How long the server should hold the connection waiting for changes, up to 25 seconds. The default 0 returns immediately. Set 20 to 25 for efficient long polling.

---

Response

Response

{
  "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": "holo3-122b-a10b",
        "input_tokens": 21166,
        "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" }
  ]
}

Field	Type	Description
status	string	Current session status.
started_at	string | null	ISO 8601 timestamp when the agent started executing.
finished_at	string | null	ISO 8601 timestamp 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	Machine-readable failure category when the session failed or timed out: environment_error, no_answer, answer_validation, timeout, or internal. See Read how the run ended.
outcome	string | null	The agent’s self-assessed task outcome, reported with its final answer: success, partial, infeasible, or blocked. See Read how the run ended.
answer	string | object | null	The agent’s final result once produced; null otherwise. A string by default, or an object matching the agent’s answer_format JSON Schema when one was set. See Polling rules for when it lands; the same value is mirrored on the Session object’s latest_answer.
metrics	object	Usage and cost rolled up to the moment of the response: steps, total_cost, input_cost, output_cost, reasoning_cost, and cost_per_model[] (each entry carries per-model tokens and costs, including reasoning_tokens). Cost fields are in USD and are null when a model’s price is unavailable, so null-check before summing.
new_events	array	Events since from_index, each following the event shape (type, data, timestamp).

---

Examples

cURL

curl "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/changes?from_index=0&wait_for_seconds=25" \
  -H "Authorization: Bearer $HAI_API_KEY"

---

Long-polling pattern

Long polling is more efficient than repeated status checks because the server only responds when something actually changes. The SDK ships a helper that runs the loop for you: it drives termination off status (authoritative) while streaming events from changes, resuming from_index and handling the 204 no-change responses automatically.

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.

Long-poll changes to follow a run: it returns new events and the final answer with near-instant latency and far fewer calls than fixed-interval polling. Reach for status only when you want a cheap, one-off liveness check.