> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle Events

A lifecycle event is recorded for every state change of a sandbox, as the change is made. Events are kept for 7 days and served by the data plane with a [token](https://developers.telnyx.com/docs/edge-compute/sandboxes/authentication.md#sandbox-token), never by the control plane.

## Read Events

| Request | Returns |
| - | - |
| `GET /sandbox/{id}/lifecycle_event` | One sandbox's events. |
| `GET /sandbox/lifecycle_event` | The organization's events in the region, across all sandboxes. |

| Parameter | Description |
| - | - |
| `since` | An RFC 3339 time. Events at or after it. Organization route only. |
| `type` | One event type. Repeats for up to 8 types. |
| `sandbox` | One sandbox ID. Organization route only. |
| `page[size]` | Events per page. Default and maximum `100`. |
| `page[after]` | The `next_page_after` cursor of the previous page. |

```bash API theme={null}
curl -G "$DATA_API/lifecycle_event" \
  --data-urlencode "since=2026-11-11T19:00:00Z" \
  --data-urlencode "type=terminated" \
  -H "Authorization: Bearer $SANDBOX_TOKEN"
```

```json Output theme={null}
{
  "data": [
    {
      "id": "evt-0193c4f0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "ts": "2026-11-11T19:34:05.218Z",
      "type": "terminated",
      "sandbox_id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d",
      "data": { "reason": "timeout" }
    }
  ],
  "meta": {
    "next_page_after": "MjAyNi0xMS0xMVQxOTozNDowNVo...",
    "page_size": 100
  }
}
```

Events are ordered by `ts`, then `id`. Two changes committed close together can appear in either order, so an event with an earlier `ts` can follow one already read. Every event has a unique `id`. A client that polls for new events therefore reads again from a `since` a few seconds before the last event it holds, and drops the events whose `id` it already has.

## Event Types

| `type` | `data` |
| - | - |
| `created` | `{}`, or `{"template": ...}`, `{"from_snapshot": ...}`, or `{"fork_of": ..., "swarm": ...}` for the source it started from |
| `started` | `{}` |
| `paused` | `{"reason": ...}`: `customer`, `idle_timeout`, or `timeout` |
| `resumed` | `{}` |
| `snapshotted` | `{"snapshot_id": ..., "name": ...}` |
| `forked` | `{"swarm": ..., "count": ..., "sandbox_ids": [...]}` |
| `network_updated` | `{"egress": ...}` |
| `terminated` | `{"reason": ..., "exit_code": ...}`, with a [termination reason](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle.md#terminate) |

An unknown type, more than 8 types, or a malformed `since` or cursor is refused with `400`. A sandbox ID of another organization is `404` on the sandbox route and an empty page on the organization route.

## Webhooks

Webhooks Preview will deliver the same events to an HTTPS endpoint as they happen.
