Events

The Events API lets you retrieve and subscribe to real-time events for a sandbox session. Events are emitted as session state changes, commands execute, snapshots are created, and resources are provisioned.

To obtain your authentication credentials, install the Release CLI and run release auth login. The CLI stores credentials in ~/.release.yaml.

---

Event Types

All events include a type field indicating what occurred. The following table lists every event type grouped by category.

Category	Event Type	Description
Session	session.created	Session was created
Session	session.running	Session is now running
Session	session.suspended	Session was suspended
Session	session.terminated	Session was terminated
Session	session.updated	Session metadata was updated
Execution	execution.started	Command execution began
Execution	execution.completed	Command execution completed
Execution	execution.failed	Command execution failed
Snapshot	snapshot.created	Snapshot was created
Snapshot	snapshot.restored	Snapshot was restored
Resource	resource.cloning	Resource is being cloned
Resource	resource.ready	Resource is ready
Resource	resource.failed	Resource failed to provision
Resource	resource.added	Resource was added to session
Resource	resource.updated	Resource was updated
Resource	resource.removed	Resource was removed from session

Note: Treat event types as open-ended — clients should ignore unknown event names and continue processing. New event types may be added in the future without a version change.

---

List Events

Returns all events for a session as a JSON array.

Endpoint

GET https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/events

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID

Status Codes

Code	Description
200	Returns array of events
401	Unauthorized — invalid or missing credentials
404	Session not found

Response Body

Returns an array of event objects.

Field	Type	Description
id	string	Unique event identifier
type	string	The event type (see Event Types)
data	object	Event-specific payload
created_at	string (ISO 8601)	When the event occurred

Example Responses

200 OK

[
  {
    "id": "evt_01",
    "type": "session.created",
    "data": {
      "session_id": "sN4kL7"
    },
    "created_at": "2026-06-01T10:00:00Z"
  },
  {
    "id": "evt_02",
    "type": "session.running",
    "data": {
      "session_id": "sN4kL7"
    },
    "created_at": "2026-06-01T10:05:00Z"
  },
  {
    "id": "evt_03",
    "type": "execution.started",
    "data": {
      "session_id": "sN4kL7",
      "execution_id": "eX3pN8"
    },
    "created_at": "2026-06-01T10:10:00Z"
  }
]

---

SSE Event Stream

Opens a persistent Server-Sent Events (SSE) connection that streams events in real time. The connection stays open until the client disconnects or the session is terminated.

Endpoint

GET https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/events/stream

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Accept	text/event-stream

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID

Query Parameters

Name	Type	Required	Description
since	string (ISO 8601)	No	Only return events after this timestamp

Request Headers

Header	Type	Required	Description
Last-Event-ID	string	No	Resume the stream from this event ID. Events with this ID and earlier are not re-sent

Status Codes

Code	Description
200	SSE stream opened (Content-Type: text/event-stream)
401	Unauthorized — invalid or missing credentials
404	Session not found

Response

The response uses Content-Type: text/event-stream. Each event is delivered in SSE format:

id: evt_04
event: execution.completed
data: {"session_id":"sN4kL7","execution_id":"eX3pN8","exit_code":0}

id: evt_05
event: resource.ready
data: {"session_id":"sN4kL7","resource_id":"rC8wQ1","resource_type":"github_repository"}

Each SSE message contains:

SSE Field	Description
id	Unique event identifier (use with Last-Event-ID to resume)
event	The event type
data	JSON-encoded event payload

Reconnection

To resume after a disconnect, pass the last received event id as the Last-Event-ID header or use the since query parameter with a timestamp. The server replays any events the client missed.