DigitalOcean API (unofficial showcase)
GET/v2/agents/sessions/{session_id}/events

StreamSessionEvents opens the session's Server-Sent Events feed.

Opens a text/event-stream of the session's canonical events, served by the MARS data plane (OHP). Each frame is event: <type> plus a data: line holding a JSON event envelope; comment lines (: keepalive) arrive about every 15s and must be ignored. Decode every data: with one envelope parser and dispatch on the envelope's type. Every stream opens with a stream.state control frame (its data is a stream_state).

Delivery is at-least-once: clients MUST de-duplicate and order by event_id (a ULID), never by seq. The same path serves two modes:

  • live attach (default): recent context, then an open stream that stays live until the client disconnects. Pass Last-Event-ID (or cursor) to resume strictly after the last event the client already rendered, suppressing the last-N context floor.
  • finite replay (replay_only=true): writes a bounded slice of the stored transcript and closes. This is what doctl agents logs uses; paginate it with replay_from.

OHP serves recent history only (bounded by Kafka retention and an event window); it is not an archive. OHP's own errors (404/429/500/503) use the DO-standard JSON {id, message, request_id} envelope (cthulhu#179797 / MARSOHS-2065); the 401 comes from the edge.

7 parameters
session_idstringrequired
The session UUID.
replay_onlybooleanoptional
Write the selected history and then close the stream, rather than going live. Does not advance the device's delivery cursor, so it never supersedes a live attach from the same device.
Default:false
replay_fromstringoptional
Event-id pagination cursor for the `replay_only` lane only; return events after this one. There is no last-N floor, so a cursor already at the head yields nothing. Ignored on a live attach.
cursorstringoptional
Query-param equivalent of `Last-Event-ID`, because a browser EventSource cannot set request headers. Takes precedence over the header when both are present. Live-attach lane only.
device_idstringoptional
Query-param equivalent of `X-Device-UUID`. Identifies one client install so its delivery cursor and live slot are its own; a second attach from the same device supersedes the first.
Last-Event-IDstringoptional
The last event this client rendered (not merely received). Its presence marks the request a reconnect, so OHP serves strictly what follows it with no last-N floor. Persist it only after rendering.
X-Device-UUIDstringoptional
A stable per-install device id. See `device_id`.

7 status codes
200An SSE stream. Each frame is `event: <type>` plus a `data:` line holding a JSON event envelope (see `stream_event`). The stream opens with a `stream.state` control frame, then events oldest-first, then either a `stream.state: live` frame (live attach) or end-of-stream (`replay_only=true`).
event_idstringoptional
run_idstringoptional
tenant_idstringoptional
DO Team ID rendered as a decimal string.
session_idstringoptional
trace_parentstringoptional
timestampstringoptional
seqintegeroptional
Producer-supplied sequence number; nonzero values increase monotonically within an ingress stream.
source_event_idstringoptional
source_event_typestringoptional
source_tenant_idstringoptional
Optional runtime-native tenant identifier; distinct from authoritative tenant_id.
producerstringoptional
Server-assigned component that submitted the event.
Allowed:agentohrohpohs
definition_idstringoptional
revision_idstringoptional
credential_binding_set_idstringoptional
typestringoptional
Canonical SPI event type. The SSE `event:` field carries the same value.
Allowed:run.startedrun.token_deltarun.tool_call_startedrun.tool_call_completedrun.human_input_requestedrun.human_input_receivedrun.completedrun.failedrun.pausedrun.resumedsession.updatedrun.state_checkpointed
dataobjectoptional
Type-specific payload, discriminated by `type` (canonical SPI shapes; numeric fields are JSON numbers): - run.started: {agent} - run.token_delta: {text} - run.tool_call_started: {tool_call_id, name, input} - run.tool_call_completed: {tool_call_id, ok, duration_ms, summary} - run.human_input_requested: {hitl_id, payload} - run.human_input_received: {hitl_id, outcome, actor, reason} - run.completed: {total_tokens_in, total_tokens_out, run_cost_micros} - run.failed: {code, message} - run.paused: {reason} - run.resumed: {} - session.updated: {} - run.state_checkpointed: {checkpoint_id, digest} - run.handoff: {from, to, description} - run.usage_recorded: {step_id, model_id, usage: {input_tokens, output_tokens, cached_input_tokens, reasoning_tokens, tool_seconds}} - run.sandbox_allocated: {sandbox_id, kind, template} - run.sandbox_released: {sandbox_id, exit_code, duration_ms} - run.cost_accrued: {running_total_micros, delta_micros} - run.log: {level, message, fields}
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Unknown session, or a session belonging to another team. The two are deliberately indistinguishable so a caller cannot enumerate other tenants' session ids.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Attach admission limit reached. Retry after the Retry-After hint.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Internal error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
503OHP cannot currently establish the caller's authorization or the session's location. Transient; retry after the Retry-After hint.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 404 is returned: Unknown session, or a session belonging to another team. The two are deliberately indistinguishable so a caller cannot enumerate other tenants' session ids. A 429 is returned: Attach admission limit reached. Retry after the Retry-After hint. A 500 is returned: Internal error. A 503 is returned: OHP cannot currently establish the caller's authorization or the session's location. Transient; retry after the Retry-After hint. Any other status is an error: There was an unexpected error.