Events

Everything that happens in a session is recorded as an ordered event: your messages, the agent’s replies, tool calls, and status changes. Send events to steer a session, and stream or list them to follow it.

You need a session id; see Sessions. Sending messages needs the organization developer or admin role. The organization user role can read and stream events. The billing role cannot see sessions. See Organizations and roles. For API calls, create a key under API keys; see API keys.

Send messages

sendSessionEvents adds turns to a session. Send message for one plain-text turn, or events for typed turns. If you send both, events wins and message and the top-level actor are ignored.

Console
cURL

Open the session, type in Message the agent…, and click Send. While the agent is working the button reads Queue, and Interrupt & send appears beside it.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {"type": "user.message", "text": "Use the incident tracker as the source of truth."},
      {"type": "system.message", "content": [{"type": "text", "text": "Reply in British English."}]}
    ]
  }'

{ "ok": true, "delivery_state": "queued", "events_accepted": 2 }

The response confirms that your turns were stored. It does not include the agent’s reply; read that from the stream or the event list. Compare events_accepted with the number of events you sent.

`delivery_state`	Meaning
`queued`	The agent is mid-turn. It reads your message at the end of the current turn. Interrupt to have it read now. Until then the message appears in pending inputs, not the transcript. See Session operations.
`signaled`	The session was waiting, and your message woke it.
`resumed`	The session was idle or finished, and your message started a new run. Only root sessions resume.
`stored`	The message was saved, but nothing is running to read it yet.

Event fields and send rules

Event field	Description
`type`	`user.message` (the default), `system.message`, or `handoff_resolved`. Any other value fails the request with `400` naming that entry, and nothing is appended.
`text`	Shorthand for one text block. Ignored when `content` is set.
`content`	Content blocks, such as `[{"type": "text", "text": "..."}]`. Wins over `text`. A `system.message` uses only `content`.
`actor`	Who a `user.message` is attributed to. Defaults to `human:api`. A `system.message` ignores it.

A user.message with neither text nor content is dropped without an error. If every entry is dropped, the request also fails with 400.The top-level referenced_session_ids grants the session read access to up to 10 earlier sessions from this turn on. If you cannot read one of them, the whole request fails with 404 and no message is delivered. See Referenced sessions.A top-level image or document block can name a file from your library instead of carrying bytes. See Show a file to the agent in a message.A message to a session that is still being cancelled returns a retryable 409 conflict. A message to a subagent session in a terminal status also returns 409 conflict, because only root sessions resume.

Retry a send safely

To retry a send after an ambiguous network failure without adding the turn twice, send one stable Idempotency-Key header and resend the same request. See Idempotent mutations.

Hand a browser step back

When a session is awaiting_human, the agent is waiting for a person to handle a step in its browser display, such as a sign-in. Its active_handoff names the request. Send a handoff_resolved event with that handoff_id to let the agent continue, with an optional note of up to 2,000 characters telling it what you did. It must be the only event in the request.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"events": [{"type": "handoff_resolved", "handoff_id": "7c2e9a41-5b38-4d06-a1f7-3e8c6b2d9f50", "note": "Signed in to the vendor portal."}]}'

A handoff_id that doesn’t match the active hand-off, or a session with none, returns 409 conflict. Without this event, the agent resumes on its own when the hand-off deadline passes.

Stream events

streamSessionEvents is a server-sent events (SSE) stream of a session’s events as they are recorded. It replays everything after your cursor first, then stays open for new events. The stream closes on its own only when the session reaches a terminal status: completed, failed, or cancelled. An interrupted or sleeping session keeps it open.

Console
cURL

Open the session. The transcript streams live.

curl -N 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events/stream' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

: connected

event: agent.message
id: 01997a3d-0b82-7c15-9a43-6e1f2d8c5b09
data: {"type":"agent.message","id":"01997a3d-0b82-7c15-9a43-6e1f2d8c5b09","session_id":"e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53","processed_at":"2026-09-25T14:05:40Z","content":[{"type":"text","text":"Found 12 open incidents."}],"raw_event":{"event_type":"message"}}

: ping

Each event is sent as event: <type>, id: <event_id>, and data: <json>. Save the id of each frame you handle: it is your position if the connection drops. See Recover from a dropped stream.

Stream parameters

Parameter	Description
`after_event_id`	Start after this event id. Takes precedence over the `Last-Event-ID` header.
`Last-Event-ID` header	Start after this event id when `after_event_id` is not set. Standard SSE clients send it on reconnect.
`types`	Only send these frame types, comma-separated (`types=agent.message,session.status_idle`) or repeated as `types[]`. Filtered-out events still move your position forward.

Every frame type

The frame’s JSON has type, id, session_id, session_thread_id, processed_at, content, stop_reason, usage, error, anchor_event_id, and raw_event, which holds the full stored event.

Frame `type`	Sent for
`user.message`, `agent.message`, `system.message`	Messages, by role.
`agent.tool_use`, `agent.tool_result`	Tool calls and their results.
`agent.approval_request`, `user.tool_confirmation`	Approval requests and decisions.
`agent.artifact`	A saved deliverable.
`agent.thread_context_compacted`	A thread’s context was compacted.
`session.status_provisioning`, `session.status_queued`, `session.status_running`	The session entered that state.
`session.status_idle`	The session went idle or completed.
`session.status_terminated`	The session failed or was cancelled.
`session.status`	Any other status change.
`session.event`	Everything else: summaries, plan updates, turn commits, advisor notes, and board updates. Read `raw_event.event_type`.
`session.error`	A problem with the stream. See Stream errors and record size.

The stream also sends frames without an id. These are not stored events and do not move your position:

: connected is the first line. : ping follows every 15 seconds. They keep the connection alive; ignore them.
When you connect to a running session, a session.status_running frame tells you the current state.
When the session reaches a terminal status, the stream sends one last session.status_idle (completed) or session.status_terminated (failed or cancelled), with stop_reason and, on failure, error. Then it closes.

Stream errors and record size

Frame	Meaning	What to do
`session.error` with an `id` and `error.code: event_record_too_large`	One event was too large to send. `error.content_path_template` gives the path to fetch it. The stream continues.	Fetch it with `getSessionEventContent`, or list events with `payloads=refs`.
`session.error` without an `id`, with `error.message`	The server could not read events. The stream closes.	Reconnect from your last event id.

The Content-Type of the response is text/event-stream; charset=utf-8; max-record-bytes=<N>, where <N> is the largest record the server may send. Size your SSE parser’s buffer to that value. If a record is larger than your client accepts, list events after your last id with payloads=refs, then resume the stream after the event you fetched.

Recover from a dropped stream

Networks drop connections. The stream is designed so you can reconnect without losing events.

Track the last event you finished processing

Save a frame’s id only after you have handled it. Frames without an id never change your position.

Reconnect from that id

Reconnect with Last-Event-ID: <id>, or with after_event_id=<id> in the URL. The server replays every event after it. If you use after_event_id, update it on every reconnect; reusing the original URL replays from the original position. A malformed id returns 400. A well-formed id from another session does not fail; it is treated as a position.

Back off between attempts

Retry with exponential backoff and jitter. A 503 means the server is at its stream capacity; retry after a short wait.

Deduplicate by event id

Replays can repeat an event you already saw, so keep a set of handled event_id values and skip repeats.

Reconcile when the session ends

When several agents write at once, an event can be recorded slightly after a later-sorting event was already sent to you, and a cursor reader can miss it. After the stream closes at a terminal status, page through listSessionEvents from the start and add any event id you have not seen.

If your process restarts and loses its place, list events with listSessionEvents to rebuild state, then open the stream with after_event_id set to the last id you listed.

List events

listSessionEvents returns events oldest first, in pages. Any session id in a tree returns the combined timeline of the whole tree, including subagents.

Console
cURL

Open the session. The transcript shows every event, and the Events tab lists them with their raw fields.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events?limit=200' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "events": [
    {
      "event_id": "01997a3c-5e21-7b4d-8f10-3c6a2e9d4b71",
      "event_type": "message",
      "actor": "human:api",
      "role": "user",
      "session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
      "content": {
        "blocks": [{ "type": "text", "text": "Use the incident tracker as the source of truth." }]
      },
      "event_status": "completed",
      "created_at": "2026-09-25T14:05:02Z"
    }
  ],
  "next_page_token": "<id of the last event on this page>"
}

To read the next page, pass next_page_token as after_event_id. An empty token means you have read everything that exists right now.

List parameters and paging

Parameter	Description
`after_event_id`	Return events after this id, not including it. Must be a lowercase event id; a malformed value returns `400`.
`limit`	Events per page. Default 100. A page also stops at about 8 MiB of data, so it can hold fewer events than `limit`.
`hydrate`	`images` inlines image data in image blocks.
`image_urls`	`signed` adds a short-lived `url` and `url_expires_at` to image blocks. A URL can be left out when many images are signed at once; fetch those with Get an image.
`payloads`	`refs` returns large tool payloads as references instead of inline, which keeps pages small.

Any other value for hydrate, image_urls, or payloads returns 400.Pagination. next_page_token is always present and equals the id of the last event on the page. A short page with a non-empty token does not mean the end. events can be null on the last page.Event ids. Event ids sort in the order events were created, so an id works as a position. An after_event_id that is well formed but not in this session is not an error: you get the events that sort after it.Oversized events. An event too large for a page is returned alone, with content_hydration_status: oversized. Fetch its full content with Get full event content.

Event fields

Field	Description
`event_id`	Unique, time-ordered id. Use it as a cursor and to deduplicate.
`event_type`	`message`, `tool_invocation`, `tool_result`, `approval_request`, `approval_decision`, `summary`, `plan_update`, `session_status`, `artifact`, `advisor_intervention`, `board_update`, `thread_context_compacted`, or `turn_committed`.
`actor`, `role`	Who produced the event. `role` is `user`, `assistant`, or `system` on messages.
`content`	`blocks`, plus `stop_reason`, `usage`, `plan`, and `metadata` where they apply.
`event_status`	`pending`, `completed`, `warning`, `error`, or a lifecycle value on `session_status` events.
`session_id`, `thread_id`	Which session and thread produced the event. See Multi-agent sessions.
`tool_name`, `tool_use_id`	On tool calls and results. A result shares `tool_use_id` with its call.
`parent_event_id`, `causal_event_id`, `turn_id`	Links to related events and the turn.
`input_tokens`, `output_tokens`, `cost_micros`	Usage on model events. `cost_micros` is for diagnostics, not what you are charged. See Usage and cost.
`content_hydration_status`	Set when content was not returned in full.
`created_at`	When the event was recorded.

Get full event content

getSessionEventContent returns the full content of one event. Use it for oversized events or payload references. The event must belong to the session. The response carries an ETag.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events/01997a3c-5e21-7b4d-8f10-3c6a2e9d4b71/content' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

Get an image

Image blocks in events carry an image URI. getSessionImage returns the image bytes for it, with the image’s media type. Call it with an HTTP client or cURL. The URI must come from an event in the same session tree. In the console, images show inline in the transcript.

curl -G 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/images' \
  --data-urlencode 'uri=<the image URI from the event>' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -o image.png

To skip this call, list events with image_urls=signed and download from each block’s short-lived url.

Watch many sessions with the gestalt

The gestalt is a live, compact summary of every root session in a time window: its status, execution state, and last activity. It is built for dashboards and alerting. Use it instead of polling listSessions or opening one event stream per session. Take one snapshot, draw it, then keep it current with the gestalt stream.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/gestalt?since=2026-09-18T00:00:00Z&agent_id=b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "as_of": "2026-09-25T14:20:03.512Z",
  "sessions": [
    {
      "session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
      "agent_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
      "status": "active",
      "execution_state": "running",
      "created_at": "2026-09-25T14:02:11Z",
      "updated_at": "2026-09-25T14:19:48Z",
      "last_activity_at": "2026-09-25T14:19:48Z"
    }
  ]
}

since is required, in RFC 3339 format. It can be at most 30 days ago, or 400 days ago when you also pass agent_id. Keep the snapshot’s as_of for the stream.

Snapshot fields

Sessions are ordered newest first by creation time. A row has failed: true when the session ended in a failure. truncated: true means only the newest 5,000 were returned; narrow the window or add agent_id. Both fields are left out when false.

Keep the snapshot current

Open streamSessionGestalt with the same since and agent_id, and after set to the snapshot’s as_of.

curl -N 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/gestalt/stream?since=2026-09-18T00:00:00Z&agent_id=b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38&after=2026-09-25T14:20:03.512Z' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

On each gestalt.change frame, replace each row by session_id and remove rows with deleted: true. The gestalt stream never closes on its own otherwise, so close it when your dashboard is done.

Gestalt frames and reconnecting

Frame	Meaning	What to do
`: connected`, `: ping`	Keep-alive. Nothing is sent while nothing changes.	Ignore.
`gestalt.change`	`data` is `{as_of, sessions}` with the rows that changed. Its `id` is the new `as_of`.	Replace each row by `session_id`. Remove rows with `deleted: true`.
`gestalt.reset`	The server cannot continue from your position. The stream closes.	Take a new snapshot and reconnect from its `as_of`.
`gestalt.error`	The server hit an error. The stream closes.	Reconnect from the last `id` you received. If it repeats, take a new snapshot.

To reconnect, send the last frame id as after or as the Last-Event-ID header. One of them is required. A stream position older than 30 days is rejected; take a new snapshot.

What can go wrong

The most common problems:

The reply never arrives after delivery_state: queued. The agent is still on its current turn. Wait, or interrupt the session.
events_accepted is lower than the events you sent. Some entries were dropped. Check each entry’s type and content.
The stream replays the same events after every reconnect. The URL still has the original after_event_id. Update or remove it on reconnect.
The stream stays open after the agent stopped. The session is interrupted or sleeping, not terminal. Close the stream yourself, or cancel the session.

Every events error

Symptom or code	Cause	Fix
`400 invalid_request` on `events`	Every event was dropped: unknown types or empty messages.	Send `text` or `content` on each `user.message`.
`events_accepted` is lower than the events you sent	Some entries were dropped.	Check each entry’s `type` and content.
`404 not_found` when sending	The session or a referenced session is missing or not visible to you.	Check the ids and your access.
`409 conflict` when sending	The session is still being cancelled.	Retry after a few seconds.
The reply never arrives after `delivery_state: queued`	The agent is still on its current turn.	Wait, or interrupt the session.
`409 conflict` when messaging a subagent	Subagent sessions in a terminal status do not resume.	Message the root session.
`400 invalid_request` on `after_event_id`	The id is malformed or not lowercase.	Pass an `event_id` exactly as returned.
The stream replays the same events after every reconnect	The URL still has the original `after_event_id`.	Update or remove it on reconnect.
`503 service_unavailable` when opening a stream	The server is at its stream capacity.	Retry with backoff.
`session.error` with `event_record_too_large`	One event is larger than a stream record.	Fetch it with `getSessionEventContent`.
An event is missing from a long stream	A concurrent write was recorded out of order.	Re-read events after the session reaches a terminal status.
The stream stays open after the agent stopped	The session is interrupted or sleeping, not terminal.	Close the stream yourself, or cancel the session.
`gestalt.reset`	Your gestalt position can no longer be continued.	Take a new snapshot.
`400 invalid_request` on `since`	The window is older than 30 days (400 with `agent_id`), or not RFC 3339.	Shorten the window or add `agent_id`.

Every error has required code and message fields plus optional details. When present, details can include field, requestId, retryable, and code-specific context. Use the generated Endpoints reference for exact alternatives and Errors for recovery guidance.

Limits on referenced sessions, event pages, stream keep-alive, and the gestalt are in Limits.

Next steps

Sessions

Start, interrupt, cancel, and delete sessions.

Session operations

Pending inputs, compute usage, the analyst, and the session tree.

Multi-agent sessions

Read events across threads and subagents.

Deliverables and artifacts

Ask for deliverables and see how they’re kept.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Send messages

Stream events

Recover from a dropped stream

List events

Get full event content

Get an image

Watch many sessions with the gestalt

Keep the snapshot current

What can go wrong

Next steps

Sessions

Session operations

Multi-agent sessions

Deliverables and artifacts

​Send messages

​Stream events

​Recover from a dropped stream

​List events

​Get full event content

​Get an image

​Watch many sessions with the gestalt

​Keep the snapshot current

​What can go wrong

​Next steps

Sessions

Session operations

Multi-agent sessions

Deliverables and artifacts

Send messages

Stream events

Recover from a dropped stream

List events

Get full event content

Get an image

Watch many sessions with the gestalt

Keep the snapshot current

What can go wrong

Next steps