Sessions

A session is one run of an agent on a task: lifecycle states, the session object, overrides, ways to wait for the result, listing and filtering.

A session moves through a fixed lifecycle. You can steer it while it runs and read the result when it finishes. Every follow-up call (sending a message, pausing, cancelling) is addressed to the session’s id. The optional max_steps and max_time_s caps bound how long it runs before the agent is asked for a final answer.

CLI

hai run "Open Hacker News and list the top 3 stories with their URLs." \
  --agent h/web-surfer-flash

Creating a session returns its id. For a one-shot run, the helper below creates the session, blocks until the agent finishes, and hands back the result.

Python

result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Open Hacker News and list the top 3 stories with their URLs.",
)
print(result.status, result.answer)

Wait for the result

Pick the call that matches how much control you need. The final answer is answer on the result object and on changes, and latest_answer on the session object.

Way	Use when	You get back
client.run_session(...) / runSession (Quickstart)	One call: create, block, read	The final result: status, answer, outcome, error_code
client.start_session(...) then session.wait_for_completion() (Watch and steer)	Read or steer while it runs, then block	A handle bound to the id, then the same final result
session.stream() (Watch and steer)	A live, read-only event feed	Each event in order until the session settles
wait_for_session(client, id) / waitForSession (Changes)	You hold an id created elsewhere	Drains changes, returns the final result
GET /sessions/{id}/changes long-poll	Raw HTTP, any language	New events plus answer once it lands
Webhooks	No polling; batches and queued runs	session.completed and the other status events
GET /sessions/{id}	Read a settled run any time	latest_answer, no cursor needed

Polling changes by hand has a few gotchas; see its polling rules.

Session object

Field	Description
id	The session’s UUID, the handle for every follow-up call.
request	Echoes what you submitted, with agent resolved to its full spec even if you passed a catalog id.
status	Carries the live status, step count, per-model token usage (usage_per_model), any error and its error_code, the agent’s self-assessed outcome, and subagent_session_ids. See Session status for the breakdown.
agent_view_url	Link to the session’s Agent View page for live viewing and replay.
latest_answer	The agent’s most recent final answer, mirrored from changes; null until it first answers.
created_at / started_at / finished_at	Track the run’s timeline. The latter two are null until they happen.

Lifecycle

Every session moves through the same state machine, whichever agent runs it:

Status	Meaning	Terminal
queued	Session accepted above your concurrency limit; it starts automatically, oldest first, as slots free up.	No
pending	Session created, agent is launching.	No
running	Agent is actively working on the task.	No
paused	Manually paused via the API. State is preserved.	No
idle	Interactive agent finished a task and is waiting for your next message.	No
awaiting_tool_results	Agent is blocked on custom tool calls your code must answer.	No
completed	Agent finished the task successfully.	Yes
timed_out	Agent exceeded the maximum allowed time.	Yes
interrupted	Session was canceled via DELETE.	Yes
failed	An unrecoverable error occurred.	Yes

Overrides

Reuse a catalog agent but adjust it for a single run with overrides, a map on the create-session body. Rather than defining a new agent, you point at fields of the resolved request. Each key is a dotted path, and its value replaces whatever that path resolves to, applied after agent is expanded from its catalog id.

• Dots walk into objects. agent.instructions sets behavior, agent.model swaps the serving model, and agent.answer_format pins a structured answer.
• A [field=value] selector picks a list member. agent.environments[kind=web] selects the web environment, so agent.environments[kind=web].start_url sets just its start page and agent.environments[kind=web].mode switches how it reads the page.
• Values are type-checked. Each value must match the type of the field its path targets. An unknown path or a wrong type is rejected with 422 at creation, before the agent runs.

For example, send a catalog web-surfer to a chosen start page:

CLI

hai run "Summarize the top discussion right now" \
  --agent h/web-surfer-flash \
  --override 'agent.environments[kind=web].start_url=https://news.ycombinator.com'

Listing and filtering

GET /api/v2/sessions pages through your sessions, newest first, with filters you can combine:

Filter	Type	Description
status	string (repeatable)	Filter by session status (e.g. ?status=running&status=queued).
agent	string (repeatable)	Filter by agent identifier (e.g. h/web-surfer-flash).
group_id	string	Filter by group: useful for multi-session workflows.
parent_session_id	string	Find child sessions of a parent.
schedule_id	string	Sessions created by a schedule’s fires.
search	string	Case-insensitive match on the first message or answer.
created_before / created_after	string	Bound by creation time (ISO 8601).
finished_before / finished_after	string	Bound by finish time (ISO 8601).
owner	string	Access scope. Default: me-in-organization.

cURL

curl "https://agp.eu.hcompany.ai/api/v2/sessions?status=running&agent=web-price-finder" \
  -H "Authorization: Bearer $HAI_API_KEY"

Responses use the standard page envelope. See List sessions for size, sort, and the full parameter reference.

Endpoints

Method	Path	Description
POST	/api/v2/sessions	Create a session
GET	/api/v2/sessions	List sessions
GET	/api/v2/sessions/{id}	Retrieve a session
GET	/api/v2/sessions/{id}/status	Get session status
DELETE	/api/v2/sessions/{id}	Cancel a session
POST	/api/v2/sessions/{id}/messages	Send a message
POST	/api/v2/sessions/{id}/tool_results	Send tool results
POST	/api/v2/sessions/{id}/pause	Pause a session
POST	/api/v2/sessions/{id}/resume	Resume a session
POST	/api/v2/sessions/{id}/force_answer	Force final answer
GET	/api/v2/sessions/{id}/changes	Long-poll for changes
GET	/api/v2/sessions/{id}/events	List events
GET	/api/v2/sessions/quota	Get quota
POST	/api/v2/sessions/{id}/feedback	Session feedback
PUT	/api/v2/sessions/{id}/events/{event_index}/feedback	Event feedback
POST	/api/v2/sessions/{id}/share	Share a session
DELETE	/api/v2/sessions/{id}/share	Unshare a session
GET	/api/v2/sessions/{id}/resources/{bucket}/{key}	Get a session resource