Get a session
PreviewOne of the caller’s sessions on an api channel, with the questions and approvals it waits on.
/v1/channels/{channel_id}/sessions/{session_id}Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Api channel ID
Session ID
Responses
200The session
The session
A session as an execution caller sees it: no instructions, tools, owners or costs, which are management’s.
object
Outcome of the last finished turn: completed, failed or cancelled.
Held-back tool calls the session waits on. Same rule as
pending_questions.
A held-back tool call the session waits on. Same shape as serve’s
pending_approvals item, plus answerable.
object
Always true: the person using the agent answers its approvals.
object
arguments is a truncated preview; the decision still binds to the
full arguments.
When the request counts as rejected (RFC 3339).
Why the gate asked: destructive, open_world, mutating or policy.
The asking agent’s session, when another agent in the run asked. Answer on this session; the server routes it.
The request to name in POST …/tool-approvals.
Question sets the session waits on. Only GET …/sessions/{id} reads
them; a list leaves them out.
An ask_user question set the session waits on. Same shape as serve’s
pending_questions item.
object
When the server stops waiting (RFC 3339).
The questions as asked: kind, id, header, question, options,
multi_select, allow_other.
object
The asking agent’s session, when another agent in the run asked. Answer on this session; the server routes it.
The ask_user call to name in POST …/question-answers.
started, active, idle, waitingforinput or failed.
What the latest turn is doing or got done. Only GET …/sessions/{id}
reads it. Under full visibility it is the whole report; otherwise
the public view: state, plan counts, facts, the agent’s own summary
and links, never step labels or approval prompts.
object
Agent name snapshot at turn start.
Elapsed time: to the end when finished, to the read time while running.
When the work ended.
One line, always present: the current step while working, the request while waiting, the result when finished.
Model of the latest generation.
Steps run but no longer listed.
The plan the agent shared, if any.
object
The item in progress, in its “doing” form when the tool has one.
Items done or skipped.
Plan items in order.
One checklist line in [BackgroundProgress::steps].
object
State of one checklist line.
Items in total.
What finished work produced. Absent while working.
object
Files, links, pull requests and sessions the work produced.
Typed link to something the task produced.
object
Session VFS path, when the artifact lives in the session filesystem.
Artifact type: “file”, “url”, “session”, “pr”, etc.
External URL, when the artifact lives elsewhere.
How the agent checked the work (“ran the 12 billing tests”), when it reported.
Measured facts, in display order.
One measured fact.
object
Which fact.
Its value.
One or two sentences on what changed.
When the work started.
Where the work stands.
Steps in order, newest last, bounded by [MAX_REPORT_STEPS].
One step of the work: a tool call, labelled by its narration.
object
How long the step took, once finished.
The tool call id.
What the step is doing (“Running tests”) or what came out of it (“Read AGENTS.md”).
When the step started.
Where the step stands.
Tool name.
The turn the report describes.
Example
{ "id": "session_01933b5a000070008000000000000001", "pending_approvals": [ { "agent": { "id": "agent_01933b5a00007000800000000000001", "name": "Research Assistant" } } ], "pending_questions": [ { "agent": { "id": "agent_01933b5a00007000800000000000001", "name": "Research Assistant" } } ], "status": "idle", "work": { "agent_name": "Billing fixer", "attention": { "kind": "approval", "prompt": "Deploy to staging" }, "duration_ms": 133000, "ended_at": "2026-10-23T12:02:13Z", "headline": "Step 3 of 4 · Running `cargo test`", "model": "gpt-6.1-sol", "omitted_steps": 0, "plan": { "current": "Run the tests", "done": 2, "items": [ { "status": "pending" } ], "total": 4 }, "result": { "checks": "Ran the 12 billing tests", "facts": [ { "kind": "files_changed", "value": 3 } ], "outcome": "done", "summary": "Fixed the proration rounding and added a test.", "summary_source": "agent" }, "started_at": "2026-10-23T12:00:00Z", "state": "working", "steps": [ { "duration_ms": 4200, "id": "call_01", "label": "Ran `cargo test`, 12 tests passed", "progress": { "current": 7, "label": "Rendering image 7 of 12", "total": 12 }, "started_at": "2026-10-23T12:00:00Z", "state": "running", "tool_name": "bash" } ], "turn_id": "turn_01933b5a00007000800000000000001" }}401Missing or invalid credentials
Missing or invalid credentials
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}403Agent not available
Agent not available
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}404Channel or session not found
Channel or session not found
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}