Skip to main content
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. 
# `hai run` creates the session and blocks until the agent answers
hai run "Top 3 stories on Hacker News?"
Creating a session returns its id, which you poll for progress and the answer as in the Quickstart. For a one-shot run, the helper below blocks until the agent finishes and hands back the result. 
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Top 3 stories on Hacker News?",
)
print(result.status, result.answer)
Pick the call that matches how much control you need:
You want to…SDK callYou get back
Run and read the answer in one shotclient.run_session(...) / runSessionBlocks, then returns the final result
Watch or steer while it runsclient.start_session(...) / startSessionA handle bound to the id; read and steer, then wait_for_completion
Drive the loop yourself (raw HTTP, other languages)POST /sessions, then long-poll changesThe session id; you poll

​
Reading the answer

There are two ways to get the agent’s answer, and they solve different problems:
  • Snapshot, anytime, by id. GET /sessions/{id} returns latest_answer, the agent’s most recent final answer, or null until it first answers. It needs no cursor and never goes stale, so it’s the simplest way to ask “is it answered yet, and what’s the answer?” once a run has settled.
  • Stream, while it runs. GET /sessions/{id}/changes carries the same answer alongside the live event feed. changes is a delta. It returns only what’s new since your cursor, and 204 No Content when nothing new has arrived. The answer rides the page that delivers the final events, so you must keep polling until the session reaches a terminal state and you’ve drained the remaining events. A 204 means “no new events yet,” not “no answer.” The SDK helpers (run_session / wait_for_session) run this loop and drain to the end for you.
For live progress, long-poll changes; to simply fetch a finished run’s result, read latest_answer. Don’t poll status for the answer: it never carries one.

​
Session object

FieldDescription
idThe session’s UUID, the handle for every follow-up call.
requestEchoes what you submitted, with agent resolved to its full spec even if you passed a catalog id.
statusCarries the live status, step count, per-model token usage (usage_per_model), any error, and subagent_session_ids. See Session status for the breakdown.
agent_view_urlLink to the session’s Agent View page for live viewing and replay.
latest_answerThe agent’s most recent final answer, mirrored from changes; null until it first answers.
created_at / started_at / finished_atTrack the run’s timeline; the latter two are null until they happen.

​
Lifecycle

The agent perceives and acts in its environment step by step, moving through the same state machine regardless of which agent runs it. While it runs you can steer with messages or lifecycle controls.
StatusMeaningTerminal
pendingSession created, agent is launching.No
runningAgent is actively working on the task.No
pausedManually paused via the API. State is preserved.No
idleInteractive agent finished a task and is waiting for your next message.No
awaiting_tool_resultsAgent is blocked on custom tool calls your code must answer.No
completedAgent finished the task successfully.Yes
timed_outAgent exceeded the maximum allowed time.Yes
interruptedSession was canceled via DELETE.Yes
failedAn 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 page instead of its default start URL: 
hai run "Summarize the top discussion right now" \
  --agent h/web-surfer-flash \
  --override 'agent.environments[kind=web].start_url=https://news.ycombinator.com'

​
Structured output

By default the agent’s answer is free-form text. Set an answer_format (a JSON Schema) on the agent, or pass a Pydantic / Zod schema to the SDKs, and the final answer comes back as typed, validated data instead. See Structured output.

​
Endpoints

MethodPathDescription
POST/api/v2/sessionsCreate a session
GET/api/v2/sessionsList sessions
GET/api/v2/sessions/{id}Retrieve a session
GET/api/v2/sessions/{id}/statusGet session status
DELETE/api/v2/sessions/{id}Cancel a session
POST/api/v2/sessions/{id}/messagesSend a message
POST/api/v2/sessions/{id}/tool_resultsSend tool results
POST/api/v2/sessions/{id}/pausePause a session
POST/api/v2/sessions/{id}/resumeResume a session
POST/api/v2/sessions/{id}/force_answerForce final answer
GET/api/v2/sessions/{id}/changesLong-poll for changes
GET/api/v2/sessions/{id}/eventsList events
GET/api/v2/sessions/quotaGet quota
POST/api/v2/sessions/{id}/feedbackSubmit session feedback
POST / DELETE/api/v2/sessions/{id}/shareShare / unshare a session
GET/api/v2/sessions/{id}/resources/{bucket}/{key}Get a session resource