Event types and states

Use this page to decode the values you read from sessions, events, outcomes, and setup runs. For how these fit together, see How it works.

Session status

status is the coarse state of a session.

`status`	Meaning
`active`	The session can work or accept another turn.
`awaiting_human`	The agent asked a person to handle a step in its browser display, which needs computer use. It resumes when you send a `handoff_resolved` event, or on its own when the hand-off deadline passes, 30 minutes by default.
`completed`	The work finished. A follow-up message on a root session starts a new turn.
`failed`	The work stopped on an error. Read `failure`. A follow-up message on a root session starts a new turn.
`cancelled`	The session was hard-stopped and its sandbox torn down. A follow-up message on a root session starts a new turn in a new sandbox.

Execution state

execution_state says what the agent loop is doing right now. It’s the authoritative signal: the event stream is written separately and can lag it.

`execution_state`	Meaning
`queued`	The agent is at its `max_concurrent_sessions` cap. The session waits for a slot.
`provisioning`	The sandbox is being prepared. Normally under a minute, and never more than 5 minutes before the session fails with `sandbox_provision_timeout`.
`running`	The agent or one of its tools is working.
`idle`	Nothing is running. `stop_reason` says why.
`completed`	The loop finished, usually because the outcome was satisfied.

Stop reasons

stop_reason is set whenever execution_state is idle or completed.

`stop_reason`	Meaning	What to do
`end_turn`	The agent finished its turn with nothing left to do. This isn’t proof the work is correct.	Read the transcript, or add an outcome to grade it.
`outcome_satisfied`	The grader passed every criterion. Pairs with `execution_state: completed`.	Nothing. The work is done.
`outcome_unmet`	The agent stopped and the grader didn’t accept the work.	Read the failed criteria, then send guidance or a new outcome.
`max_iterations`	Grading reached its `max_iterations` cap with a criterion still failing.	Read the failed criteria. Define a new outcome to continue.
`grader_failed`	A grading pass produced no usable verdict, so the work is still ungraded.	Send a follow-up to retry.
`requires_action`	The agent is blocked on something only a person can settle, such as a repeated failure.	Fix the cause, then reply to continue.
`sleeping`	The agent chose to wait for a person, an external system, or a timer. It resumes on the next message or at `wake_at`.	Nothing, or send a message to wake it.
`awaiting_subagents`	A coordinating agent is waiting for delegated work to report back.	Nothing.
`interrupted`	A person interrupted the turn.	Send a message to continue.
`error`	The loop failed after its retries. The session stays resumable.	Read `failure`, then send a follow-up to retry.

Event types

Each event has an event_type. Events are append-only and ordered.

`event_type`	What it records
`message`	A message from a person, the agent, or the system.
`tool_invocation`	A tool call the agent made, with its arguments.
`tool_result`	The result of a tool call.
`summary`	A summary of earlier work, kept so the agent retains context in long sessions.
`plan_update`	A change to the agent’s current plan.
`session_status`	A change to `status` or `execution_state`.
`artifact`	A file, image, or other output the agent produced.
`turn_committed`	A checkpoint at the end of a turn.
`thread_context_compacted`	The point where older context was summarized for future turns. The original events stay in the log.
`approval_request`	The agent asked a person to take over its browser display. The session shows `awaiting_human` until the hand-off ends.
`approval_decision`	How an `approval_request` was resolved.
`advisor_intervention`	The service noticed the session may be stuck and recorded a notice, with the events that prompted it. Controlled by `multiagent.interventionist.mode`: `shadow` only records the event, `active` also sends the agent a notice it reads on its next turn, and `off` records nothing. Omitted, it uses `active`. See Configure a roster.
`outcome_evaluation`	One grading pass for an outcome.
`board_update`	A change to a team’s shared task board: a task posted, claimed, updated, or released, or a note or decision posted. Written to the root session.

See Events to list, stream, and resume events.

Outcomes

Outcome status

`status`	Meaning
`pending`	No grading pass has started.
`running`	The agent is working toward the outcome.
`evaluating`	A grading pass is in progress.
`terminal`	Grading finished. Read `terminal_result`.

Results

Each grading pass has a result. The outcome’s terminal_result is the final one.

Result	Meaning
`needs_revision`	At least one criterion failed. The agent gets the feedback and works another turn. Never a terminal result.
`satisfied`	No criterion failed. The outcome ends.
`max_iterations_reached`	A criterion still failed on the last allowed pass. The outcome ends.
`failed`	The rubric couldn’t be graded. The outcome ends.

Criterion verdicts

`verdict`	Meaning
`pass`	The work meets the criterion.
`fail`	The work doesn’t meet it. `rationale` explains why, and `evidence_event_ids` point to the events behind the judgment.
`not_applicable`	The criterion doesn’t apply to this run. It doesn’t count as a failure.

Session failures

A failed session has a failure object.

Field	Meaning
`code`	Stable failure code. See Session failure codes.
`phase`	The stage that failed, such as `provisioning`, `setup`, `credentials`, or `model`.
`category`	`transient`, `caller_error`, or `internal`. Tells you who can act.
`retryable`	Whether a retry may succeed on its own.
`message`	A short, safe explanation.
`at`	When the failure was recorded.

Environment setup

Setup verification

An environment’s setup_verification.status says whether sessions can use it.

`status`	Meaning
`not_applicable`	No setup script, so no test is needed.
`never`	A script exists but has never been tested. Sessions can’t start yet.
`running`	A setup test is in progress, and no earlier test passed. Re-testing a `verified` environment keeps it `verified` until the new test finishes.
`verified`	The latest test passed. Sessions can start unless `stale` is `true`.
`failed`	The latest test failed. Fix the script and test again.

stale: true means the environment changed after its last test, so the result no longer applies. Changing the name, description, or metadata doesn’t make it stale.

Setup-run status and phase

`status`	Meaning
`queued`	Waiting to start.
`provisioning`	Compute is being prepared.
`running`	The script is running.
`succeeded`	The script passed.
`failed`	The run failed. Read `failure_code`, `phase`, and `stderr_tail`.
`cancelled`	The run was cancelled.

phase is the stage the run reached: provision, gpu_check, setup, profile, commit, or cleanup. A failure in setup points at your script. A failure in another phase is usually temporary, so retry once before changing the script.

Account states

Resource	Values	Details
API key `status`	`active`, `inactive`, `expired`, `revoked`	API keys

Next steps

Errors

Every HTTP error code and session failure code.

Limits

Every size, count, and time limit.

Events

List, stream, and resume session events.

Glossary

Definitions of every term.

API reference

Endpoints

Event types and states

Session status

Execution state

Stop reasons

Event types

Outcomes

Outcome status

Results

Criterion verdicts

Session failures

Environment setup

Setup verification

Setup-run status and phase

Account states

Next steps

Errors

Limits

Events

Glossary

​Session status

​Execution state

​Stop reasons

​Event types

​Outcomes

​Outcome status

​Results

​Criterion verdicts

​Session failures

​Environment setup

​Setup verification

​Setup-run status and phase

​Account states

​Next steps

Errors

Limits

Events

Glossary

Session status

Execution state

Stop reasons

Event types

Outcomes

Outcome status

Results

Criterion verdicts

Session failures

Environment setup

Setup verification

Setup-run status and phase

Account states

Next steps