Sessions

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 "Top 3 stories on Hacker News?" \
  --agent h/web-surfer-flash

SESSION=$(curl -s -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent": "h/web-surfer-flash", "messages": [{"type": "user_message", "message": "Top 3 stories on Hacker News?"}]}' | jq -r .id)
echo "$SESSION"

from hai_agents import Client

client = Client()

session = client.sessions.create_session(
    agent="h/web-surfer-flash",
    messages=[{"type": "user_message", "message": "Top 3 stories on Hacker News?"}],
)
print(session.id)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const session = await client.sessions.createSession({
  body: {
    agent: "h/web-surfer-flash",
    messages: [{ type: "user_message", message: "Top 3 stories on Hacker News?" }],
  },
});
console.log(session.id);

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)

const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Top 3 stories on Hacker News?",
});
console.log(result.status, result.answer);

Pick the call that matches how much control you need:

You want to…	SDK call	You get back
Run and read the answer in one shot	`client.run_session(...)` / `runSession`	Blocks, then returns the final result
Watch or steer while it runs	`client.start_session(...)` / `startSession`	A 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 `changes`	The session `id`; you poll

Reading the answer

The simplest is the session snapshot. 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 once a run has settled it is the easiest way to read the answer. While a run is active, GET /sessions/{id}/changes carries the same answer alongside the live event feed. Because changes returns only what is new since your cursor (and 204 No Content when nothing new has arrived), the answer rides the page that delivers the final events. Keep polling until the session reaches a terminal state and you have 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. Don’t poll status for the answer: it never carries one.

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 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'

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent": "h/web-surfer-flash",
    "messages": [{"type": "user_message", "message": "Summarize the top discussion right now"}],
    "overrides": {"agent.environments[kind=web].start_url": "https://news.ycombinator.com"}
  }'

session = client.sessions.create_session(
    agent="h/web-surfer-flash",
    messages="Summarize the top discussion right now",
    overrides={"agent.environments[kind=web].start_url": "https://news.ycombinator.com"},
)

const session = await client.sessions.createSession({
  body: {
    agent: "h/web-surfer-flash",
    messages: "Summarize the top discussion right now",
    overrides: { "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.

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 "https://agp.eu.hcompany.ai/api/v2/sessions?status=running&agent=web-price-finder" \
  -H "Authorization: Bearer $HAI_API_KEY"

page = client.sessions.list_sessions(status=["running"], agent=["web-price-finder"])
for summary in page.items:
    print(summary.id, summary.status)

const page = await client.sessions.listSessions({
  status: ["running"],
  agent: ["web-price-finder"],
});
for (const summary of page.items) {
  console.log(summary.id, summary.status);
}

Like every list endpoint, it returns a page envelope: items holds the resources, page echoes the page number you asked for, and total counts all matches. Responses don’t echo size back, so track it yourself; there are more pages while page * size < total. This endpoint caps size at 100 and sorts by -created_at (newest first) unless you pass sort=created_at. See List sessions for 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`	Submit session feedback
`POST` / `DELETE`	`/api/v2/sessions/{id}/share`	Share / unshare a session
`GET`	`/api/v2/sessions/{id}/resources/{bucket}/{key}`	Get a session resource

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

Reading the answer

Session object

Lifecycle

Overrides

Structured output

Listing and filtering

Endpoints

​Reading the answer

​Session object

​Lifecycle

​Overrides

​Structured output

​Listing and filtering

​Endpoints

Reading the answer

Session object

Lifecycle

Overrides

Structured output

Listing and filtering

Endpoints