Agents APISessions
Manage sessions
Check a session's state, pause and resume it, fork it, find your sessions, and clean up.
Session state
const current = await sessions.get(session.id)
console.log(current.status, current.last_seq, current.error){
"id": "ags_4843742656c9cbc90685c6d2",
"object": "agent.session",
"status": "idle",
"agent": { "model": "anthropic/claude-sonnet-5.5", "instructions": "Answer in one short sentence.", "permissions": null },
"environment": { "type": "none", "network": "open" },
"metadata": { "customer": "cus_123" },
"created_at": "2026-09-28T07:17:41.522000+00:00",
"updated_at": "2026-09-28T07:17:52.106000+00:00",
"paused_at": null,
"ended_at": null,
"instance_number": 1,
"instance_context": "new",
"last_seq": 8,
"error": null,
"stop_reason": null,
"limits": {
"max_turns": null,
"max_tokens": null,
"max_cost_usd": null,
"spent": { "turns": 1, "tokens": 14210, "cost_usd": 0.0071, "subagents": { "turns": 0, "tokens": 0, "cost_usd": 0.0 } }
},
"usage": {
"input_tokens": 6,
"output_tokens": 14,
"cache_read_tokens": 0,
"cache_write_tokens": 14190,
"reasoning_tokens": 0,
"model_calls": 1,
"estimated_cost_usd": 0.0071,
"sandbox_seconds": 11,
"as_of": "2026-09-28T07:17:53.004000+00:00"
}
}| Field | Meaning |
|---|---|
| status | Where the session is in its lifecycle (below). |
| last_seq | The newest event number. Pass it as after to read only what comes next. |
| last_activity_at | When it last did something: a step, a message, an answer or a file change. |
| error | { type, message } if something went wrong with the sandbox, otherwise null. |
| instance_number · instance_context | Whether the conversation was restored after a pause: instance_context is full, workspace_only or new. instance_number goes up by one each time the session resumes (see Pause and resume). |
| environment · metadata | The repositories it works on and its network, and your own key/values. |
| pause_reason | Why it is paused: requested, idle_timeout, hard_limit, the spend limit it reached, or restored after a stop was undone. |
| volume_kept_until | When stopped: its disk is kept until then, and a resume before it brings the session back. Its files can't be read while it is stopped: resume it first, or name them in outputs to keep them. |
| stop_reason | Why it ended: deleted or paused_expired. A session made with end_after_run stops with run_finished after its run, or with idle_timeout or hard_limit where another session would pause. null while it lives. |
| limits · usage | Its spend caps and what counts toward them. usage, on a single read only, is the fuller sum and runs a little behind. See Spend limits. |
Statuses
| Status | Meaning |
|---|---|
| provisioning | A sandbox is starting. Messages sent now are delivered when it's ready. |
| idle | Ready and not working. A message starts a run. |
| running | Working on a run. A message steers it. |
| waiting | Blocked on an approval. |
| pausing · paused | The sandbox has been released. The conversation and files are kept, and a message resumes it. A session paused at a spend limit continues once the limit is raised. |
| stopping · stopped | Deleted, or paused for too long. stop_reason says which. Its disk is kept for 7 days, and a resume in that time brings it back. Events and patches can still be read. |
| failed | Couldn't start, for example because its sandbox wasn't ready within 240 seconds (start_timeout). See error, and create a new session. |
Pause and resume
Sandboxes are temporary, but sessions aren't. A pause keeps everything: the session's files and its conversation live on its own disk, not in the sandbox. The next message starts a new sandbox on the same disk, and the agent carries on where it left off.
await sessions.pause(session.id)
await sessions.wait(session.id, { until: ["paused"] })
// Later: a message resumes it. No need to call resume() first.
const { last_seq } = await sessions.get(session.id)
await sessions.message(session.id, "What word did I ask you to remember?")
for await (const event of sessions.events(session.id, { after: last_seq })) {
if (event.type === "text.ended") console.log(event.data?.text)
if (event.type === "run.completed" || event.type === "run.failed") break
}
const resumed = await sessions.get(session.id)
console.log(resumed.instance_number, resumed.instance_context)You asked me to remember the word "pelican".
2 fullThe session resumed (instance_number: 2) with the whole conversation restored (instance_context: "full"). With workspace_only, the files came back but the conversation starts over, so include the context the agent needs in your message. new means the session hasn't been resumed yet.
| Sessions pause or stop on their own | Default |
|---|---|
| Idle, with nothing to do → paused | 30 minutes |
| One sandbox running for a long time → paused | 4 hours |
| Paused and untouched → stopped | 4 months (120 days) |
After the 4-hour limit, the next message continues the session in a new sandbox on the same disk. A session left paused for 4 months is stopped with stop_reason paused_expired, and its disk is deleted 7 days later.
A session that's waiting for an approval is never paused for being idle. These are the defaults; your administrator may set others. If a sandbox disappears unexpectedly, the session moves to paused with an error, and the next message resumes it with its files.
Fork a session
A fork is a new session that starts from another one as it is now: the same model, repositories and network, the source's changes to its repositories, and its conversation. The two then go on separately, so you can try a second approach without losing the first.
fork = client.agents.sessions.fork(session["id"], input="Try it without the cache.")
print(fork["id"], fork["forked_from"]) # {"session_id": "ags_…", "seq": 42}const fork = await client.agents.sessions.fork(session.id, { input: "Try it without the cache." })- Only an
idlesession can be forked. A running or waiting one is refused with 409 until its run ends; a paused one must be resumed first. - Each repository starts at the commit the source was cloned at, with the source's changes on top. Commits the source made, pushed or not, arrive as uncommitted changes.
- Files outside the repositories (
uploads/,out/) are not carried over. - Spend starts at zero.
metadata,outputsandend_after_rundefault to the source's;limitsare the source's caps, with any you pass replacing them. - The fork's events start at 1. Its
forked_fromnames the source and the source's last event at the time.
Find your sessions
Sessions are listed newest first, 20 per page by default and up to 100. Use metadata to tie them to your own records. You only ever see sessions you created, in the organization you're working in.
const page = await sessions.list({ limit: 20 })
const mine = page.data.filter((s) => s.metadata?.customer === "cus_123")
console.log(mine.map((s) => `${s.id} ${s.status}`))When has_more is true, pass next_after as after for the next page.
Over HTTP, GET /v1/agents/sessions?status=waiting,paused lists only the statuses you name, and ?needs_you=true only the sessions waiting on you. GET /v1/agents/sessions/summary counts your sessions by status, says how many wait on you (waiting for an answer, or paused at a spend limit), and adds up what the sessions started in the last 24 hours have spent.
Delete a session
Deleting stops the session and releases its sandbox. Its disk is kept for 7 days (volume_kept_until): a resume() in that time undoes the delete, with every file and the conversation. After that the disk is deleted, so download any files you need. A final patch is saved when it stops, and events and patches stay readable afterwards.
const stopped = await sessions.delete(session.id)
console.log(stopped.status)finally block, as every example on these pages does.Retry safely
Pass an idempotency key when creating sessions from code that may run twice, such as a queue worker or a webhook handler. A second call with the same key returns the first session instead of starting another. The same key with different settings raises conflict.
const settings = {
agent: { model: "anthropic/claude-sonnet-5.5" },
input: `Summarize ticket ${ticket} in one line.`,
idempotencyKey: `summarize-${ticket}`,
}
const first = await sessions.create(settings)
const retry = await sessions.create(settings) // e.g. your job queue ran twice
console.log(first.id === retry.id) // true: one session, not two- When there's no capacity, creating or resuming fails with
runner_unavailable. Retry after a short wait, with the same key. - Your organization may cap active sessions. Past the cap, creation fails with
session_limit_reached.