Run the session loop

This is the complete contract for driving a session turn by turn. The quickstart runs one happy-path turn; this page covers the ordering rule that trips people up, how errors travel, how to index turns, and how to recover from each failure. If you follow one thing here, make it the loop order.

The loop order

Each turn hands you a decision and a session status. Act on them in this order:

If action_name is non-null, execute it first, even if this turn is terminal. A non-null action is always yours to run. If executing fails, add an error block to your next turn.
Then honor session_status. If it is anything other than open (completed, gave_up, closed, max_turns, spend_cap_reached, balance_exhausted), stop, after executing any action from step 1.
Otherwise (open), take the next turn. If you executed an action, capture the new frame and submit at turn_index + 1. If action_name was null (an intent no_match or none_needed), execute nothing, the world is unchanged, and submit the next turn anyway. The outcome feeds back to the participant.

A terminal turn can still carry your last action. The participant often bundles their final action with done in the same response: a non-null action_name and a terminal session_status together. Checking “is the session over?” first and skipping the action silently fails any task whose last step is an action. The TV never powers off; the order never places. session_status describes the participant’s decision state, never your obligation to execute a returned action.

The participant may also split the two: the action on a continue turn, then done with a null action_name on the next turn. Both bundled and split are valid, and the ordering above handles both. Execute a non-null action, then check the status.

Errors are observations

There is no separate “executed” field on a turn. When an action you executed fails, you report it as an error observation block on the next turn, alongside the image:

{
  "turn_index": 3,
  "observation": [
    { "type": "image", "data": "<base64 PNG>" },
    { "type": "error", "data": "The power button did not respond." }
  ],
  "valid_actions": [ ... ]
}

A failed execution is something a person would perceive, a dead button or a blocked door, so it travels through the same channel as everything else the participant senses. One turn carries exactly one image block; the optional error block is additional, never a second image.

Turn indexing

The turn_index on a turn must equal the session’s current turn count. The first turn is 0, and every recorded turn increments it by one. Every returned turn is recorded, including no_match and none_needed turns. Drive the next index off the response’s turn_index, plus one, not off whether you executed anything. Two cases move differently:

A 502 decision_invalid records nothing. Retry the same turn_index with a fresh frame.
A 409 turn_index_mismatch hands you the index the server expected. Resubmit with turn_index set to that expected_turn_index.

Reading the trace

Read a session back to replay its decisions. The trace is a cursor page: pass after_index to get turns strictly after an index and limit to size the page (default 50, max 200). Page again with after_index set to the last index you received while has_more is true.

curl -sS "$API_URL/api/v1/sessions/$SESSION_ID?after_index=0&limit=50" \
  -H "Authorization: Bearer $TOKEN"

The model behind the page is in sessions and turns.

Idempotency and replay

The create call takes an optional Idempotency-Key header. The same key with the same body returns the existing session (200, not 201); the same key with a different body is a 409 with error_kind: idempotency_conflict. Every create on the API takes the header on the same terms, so a retried registry write is as safe as a retried session: sessions, environments, environment versions, and tasks. Each create looks its key up in its own scope, the workspace for sessions, environments, and tasks, and the parent environment for a version, so the same string on two different creates never collides. Turns have a related safety net. An exact-duplicate replay of your final turn, the same turn_index, the same observation, the same valid_actions, returns the stored decision even after the session has ended. Replay is checked before the “is the session open?” guard, so a lost response to the last turn is always safe to retry. A different body at that index is a turn_index_mismatch.

Handling errors

These are the errors the session loop itself produces. Branch on detail.error_kind, not on the status. Every kind the API returns, including the registry ones this table leaves out, is in the error reference.

Status	When	What to do
`401` `invalid_api_key`	Missing, malformed, unknown, or revoked API key, all one kind	Check the `Authorization` header. See authentication.
`402` `credits_exhausted` / `plan_allowance_exhausted` / `spend_cap_reached`	The turn could not be paid for and was not applied	Terminal. The three kinds have three different remedies; see billing and limits.
`403` `insufficient_scope`	The key lacks the scope this call needs; `detail.required_scope` names it	Use a key carrying that scope.
`403` `person_out_of_scope`	The person is not workspace-owned or platform-library	Use an in-scope `person_id`.
`404`	Workspace, session, person, environment, or task not found or unreachable by your token	Check the ids and that your token’s workspace owns them. The kind names which one.
`409` `turn_index_mismatch`	Wrong turn index	Resubmit with `turn_index` set to the `expected_turn_index` in the body.
`409` `session_not_open`	You posted a turn after the session closed or terminated	The session is terminal; start a new one.
`409` `idempotency_conflict`	Reused an `Idempotency-Key` with a different body	Use a fresh key, or send the identical body to replay.
`413`	Request body too large (the base64 frame)	Reduce the frame’s dimensions. See frame size.
`422`	Validation error (two envelope shapes, below)	Fix the payload.
`429` `rate_limited` / `session_quota_exceeded`	The key’s per-minute request rate, or its daily session-create quota	Transient. Honor `Retry-After`; the two reset on different clocks.
`502` `decision_invalid`	The participant produced an invalid choice twice; no turn was recorded	Retriable: resubmit the same `turn_index` with a fresh frame.

Two shapes of 422

Validation errors come back in two shapes, so parse defensively:

A malformed request (wrong types, a missing field, an invalid observation type, a bad enum value, parameters outside the allowed subset) returns a structured envelope with an errors array of field locations:

{
  "error": "Validation error",
  "error_code": "validation_error",
  "status": 422,
  "retryable": false,
  "detail": "Validation error",
  "errors": [ { "loc": ["body", "observation", 0, "type"], "msg": "...", "type": "..." } ]
}

A business-rule rejection raised inside the endpoint (for example “exactly one image observation block is required”, or a declared-action that is not enum-or-string) returns a plain detail:
{ "detail": "exactly one image observation block is required", "request_id": "..." }

Billing and limits

Two limits can end or block a session for cost or capacity reasons, separate from the participant’s own termination. Running out of budget. Each turn accrues credits against the organization’s credit pool, and the charge settles when the session ends. A turn that cannot be paid for is refused with a 402 and is not applied; the session becomes terminal. Three refusals, three remedies. Branch on detail.error_kind, not on the status, because the first two share one status:

`error_kind`	Terminal status	What to do
`credits_exhausted`	`balance_exhausted`	No spendable credits left. Top up.
`plan_allowance_exhausted`	`balance_exhausted`	The plan’s allowance for this period is spent. It refreshes on the date in the message, or top up to continue now.
`spend_cap_reached`	`spend_cap_reached`	The workspace’s own per-period spend cap. Raise it, or wait for the period to roll over.

The session also records the reason as ended_reason, so a session you read back later still says which of the two balance_exhausted cases it was. Treat any terminal status as “stop the loop”; to continue, resolve the cause and open a new session. Session-create quota (per key). An API key has a cap on how many sessions it can open per day. A create that exceeds it returns a 429. Unlike the spend cap, this is transient: back off and retry the create later. It applies to API keys only, not to user tokens.

Open unions: tolerate unknown values

sentiment, session_status, resolution, and the observation block type are open unions. New values may be added over time. Tolerate a value you do not recognize rather than hard-failing on it. spend_cap_reached is a live example: it joined session_status after the first statuses shipped. The 11 sentiments today are Delighted, Excited, Confident, Satisfied, Relieved, Neutral, Confused, Uncertain, Anxious, Frustrated, and Disengaged, and felt_intensity is one of mild, moderate, or strong.

The reference loop

The whole contract in one place, in any language:

create session               -> session_id ; turn_index = 0 ; pending_error = null
loop:
    actions = observe_available_actions()        # what a user could do right now
    frame   = capture_frame_png_base64()         # the current view
    obs     = [ {type:"image", data:frame} ] + (pending_error ? [pending_error] : [])
    resp    = POST /sessions/{id}/turns  { turn_index, observation:obs, valid_actions:actions }
        on 409 turn_index_mismatch -> turn_index = err.expected_turn_index ; continue
        on 502 decision_invalid    -> retry SAME turn_index with a fresh frame
    d = resp.decision
    if d.action_name != null:                     # ALWAYS execute a non-null action FIRST,
        ok = execute(d.action_name, d.arguments)  # even on a terminal turn (action + done can bundle)
        pending_error = ok ? null : {type:"error", data:"<what failed>"}
    else:
        pending_error = null                      # no_match / none_needed: nothing to execute
    if resp.session_status != "open": break       # THEN stop: completed / gave_up / max_turns
    turn_index = resp.turn_index + 1              # every returned turn is recorded
POST /sessions/{id}/close                    # when you are done; returns the final session

Author your environment

Declare actions, write labels, size frames.

Score outcomes

Judge success from your state, not the participant’s words.

Get started

Core concepts

Guides

API reference

Versioning and changes

Run the session loop

The loop order

Errors are observations

Turn indexing

Reading the trace

Idempotency and replay

Handling errors

Two shapes of 422

Billing and limits

Open unions: tolerate unknown values

The reference loop

Author your environment

Score outcomes

​The loop order

​Errors are observations

​Turn indexing

​Reading the trace

​Idempotency and replay

​Handling errors

​Two shapes of 422

​Billing and limits

​Open unions: tolerate unknown values

​The reference loop

​Related

Author your environment

Score outcomes

The loop order

Errors are observations

Turn indexing

Reading the trace

Idempotency and replay

Handling errors

Two shapes of 422

Billing and limits

Open unions: tolerate unknown values

The reference loop

Related