> For the complete documentation index, see [llms.txt](https://docs.cedana.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cedana.ai/references/api/events.md).

# Events

Cedana API for events

## GET /v1/checkpoints/{id}/storage

> Storage timeline and current residency of a CSX checkpoint

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for events","name":"Events"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"CheckpointStorage":{"properties":{"checkpoint_id":{"type":"string"},"events":{"description":"Checkpoint, restore and CSX storage events for this checkpoint, oldest first.","items":{"$ref":"#/components/schemas/NotificationEvent"},"type":"array"},"residency":{"description":"Where the checkpoint lives now, per node and tier.","items":{"$ref":"#/components/schemas/Residency"},"type":"array"},"truncated":{"description":"More events exist than were returned; only the newest are included.","type":"boolean"},"write":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CsxWrite","description":"Set while the checkpoint is still being written."}]}},"required":["checkpoint_id","residency","events","truncated"],"type":"object"},"NotificationEvent":{"properties":{"action":{"description":"Storage rows: the CSX action (cached, evicted, persisted, read_closed, write_closed, ...); empty otherwise.","type":"string"},"action_id":{"type":"string"},"checkpoint_id":{"type":"string"},"cluster_id":{"type":"string"},"context":{"type":"string"},"description":{"type":"string"},"duration_ns":{"format":"int64","minimum":0,"type":"integer"},"failure_reason":{"type":"string"},"failure_stage":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"namespace":{"type":"string"},"node_name":{"type":"string"},"operation":{"type":"string"},"pause_ns":{"description":"Checkpoints: time the workload was held (see facts::checkpoint_pause_ns).","format":"int64","minimum":0,"type":"integer"},"physical_bytes":{"format":"int64","minimum":0,"type":"integer"},"pod_ready_at_ms":{"format":"int64","type":["integer","null"]},"pod_scheduled_at_ms":{"description":"Restores: PodScheduled / Ready transitions of the restored pod, once known.","format":"int64","type":["integer","null"]},"pod_uid":{"type":"string"},"read":{"type":"boolean"},"restore_uuid":{"type":"string"},"result":{"type":"string"},"storage_tier":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"},"workload_type":{"type":"string"},"write_target":{"description":"Write rows: where the write landed, tmpfs (the buffer) or nfs; empty otherwise.","type":"string"}},"required":["id","timestamp","type","operation","result","description","context","read","cluster_id","workload_type","node_name","pod_uid","name","namespace","action_id","checkpoint_id","restore_uuid","storage_tier","failure_stage","failure_reason","duration_ns","physical_bytes","pause_ns","action","write_target"],"type":"object"},"Residency":{"description":"Where a checkpoint currently lives. `node_name` is empty for NFS, which every node shares.","properties":{"bytes":{"format":"int64","minimum":0,"type":"integer"},"node_name":{"type":"string"},"since_ms":{"format":"int64","type":"integer"},"state":{"description":"writing | persisting | copying | present","type":"string"},"tier":{"type":"string"}},"required":["node_name","tier","state","bytes","since_ms"],"type":"object"},"CsxWrite":{"description":"A checkpoint still being written on a node; it lives on no tier until it reaches NFS.","properties":{"bytes":{"description":"0 while the write is still open.","format":"int64","minimum":0,"type":"integer"},"node_name":{"type":"string"},"since_ms":{"format":"int64","type":"integer"},"state":{"description":"writing | persisting","type":"string"},"target":{"description":"tmpfs (the write buffer) or nfs (written straight to NFS)","type":"string"}},"required":["node_name","target","state","since_ms","bytes"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/checkpoints/{id}/storage":{"get":{"operationId":"get_checkpoint_storage","parameters":[{"description":"Checkpoint ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointStorage"}}},"description":"Storage timeline and residency"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid checkpoint ID"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"ClickHouse unavailable"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Storage timeline and current residency of a CSX checkpoint","tags":["Events"]}}}}
```

## GET /v1/csx/residency

> Where every CSX checkpoint of a cluster lives, with per-node cache usage

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for events","name":"Events"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"ClusterResidency":{"properties":{"checkpoints":{"description":"Checkpoints that still live somewhere, newest first.","items":{"$ref":"#/components/schemas/CsxCheckpoint"},"type":"array"},"nfs_bytes":{"format":"int64","minimum":0,"type":"integer"},"nfs_checkpoints":{"format":"int32","minimum":0,"type":"integer"},"nodes":{"items":{"$ref":"#/components/schemas/CsxNode"},"type":"array"}},"required":["nodes","nfs_bytes","nfs_checkpoints","checkpoints"],"type":"object"},"CsxCheckpoint":{"properties":{"bytes":{"format":"int64","minimum":0,"type":"integer"},"checkpoint_id":{"type":"string"},"first_seen_ms":{"format":"int64","type":"integer"},"last_event_ms":{"format":"int64","type":"integer"},"last_read":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CsxRead"}]},"name":{"type":"string"},"namespace":{"type":"string"},"reads":{"format":"int32","minimum":0,"type":"integer"},"residency":{"items":{"$ref":"#/components/schemas/Residency"},"type":"array"},"write":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CsxWrite","description":"Set while the checkpoint is still being written."}]}},"required":["checkpoint_id","name","namespace","bytes","first_seen_ms","last_event_ms","residency","reads"],"type":"object"},"CsxRead":{"properties":{"at_ms":{"format":"int64","type":"integer"},"duration_ns":{"format":"int64","minimum":0,"type":"integer"},"node_name":{"type":"string"},"tier":{"type":"string"}},"required":["node_name","tier","at_ms","duration_ns"],"type":"object"},"Residency":{"description":"Where a checkpoint currently lives. `node_name` is empty for NFS, which every node shares.","properties":{"bytes":{"format":"int64","minimum":0,"type":"integer"},"node_name":{"type":"string"},"since_ms":{"format":"int64","type":"integer"},"state":{"description":"writing | persisting | copying | present","type":"string"},"tier":{"type":"string"}},"required":["node_name","tier","state","bytes","since_ms"],"type":"object"},"CsxWrite":{"description":"A checkpoint still being written on a node; it lives on no tier until it reaches NFS.","properties":{"bytes":{"description":"0 while the write is still open.","format":"int64","minimum":0,"type":"integer"},"node_name":{"type":"string"},"since_ms":{"format":"int64","type":"integer"},"state":{"description":"writing | persisting","type":"string"},"target":{"description":"tmpfs (the write buffer) or nfs (written straight to NFS)","type":"string"}},"required":["node_name","target","state","since_ms","bytes"],"type":"object"},"CsxNode":{"properties":{"disk_checkpoints":{"format":"int32","minimum":0,"type":"integer"},"disk_limit_bytes":{"format":"int64","minimum":0,"type":"integer"},"disk_used_bytes":{"format":"int64","minimum":0,"type":"integer"},"memory_checkpoints":{"format":"int32","minimum":0,"type":"integer"},"memory_limit_bytes":{"format":"int64","minimum":0,"type":"integer"},"memory_used_bytes":{"description":"Includes copies in flight, which CSX reserves up front.","format":"int64","minimum":0,"type":"integer"},"node_name":{"type":"string"},"started_ms":{"description":"Last CSX start; the node's caches were empty then.","format":"int64","type":["integer","null"]},"version":{"type":"string"},"write_buffer_bytes":{"description":"Bytes of finished writes still in the tmpfs buffer, waiting to be persisted to NFS.","format":"int64","minimum":0,"type":"integer"},"writes_in_flight":{"format":"int32","minimum":0,"type":"integer"}},"required":["node_name","version","memory_limit_bytes","disk_limit_bytes","memory_used_bytes","disk_used_bytes","write_buffer_bytes","writes_in_flight","memory_checkpoints","disk_checkpoints"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/csx/residency":{"get":{"operationId":"get_csx_residency","parameters":[{"description":"Cluster to summarize","in":"query","name":"cluster_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterResidency"}}},"description":"Cluster CSX residency"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"ClickHouse unavailable"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Where every CSX checkpoint of a cluster lives, with per-node cache usage","tags":["Events"]}}}}
```

## GET /v1/events

> Recent checkpoint and restore results, newest first (the UI notification feed)

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for events","name":"Events"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"EventsResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/NotificationEvent"},"type":"array"},"source_checkpoints":{"description":"Successful checkpoints that finished before the window but were restored inside it, so a restore can be\ncompared with its source pod's cold start. Checkpoints taken from a pod that was itself restored are left out.","items":{"$ref":"#/components/schemas/NotificationEvent"},"type":"array"}},"required":["events","source_checkpoints"],"type":"object"},"NotificationEvent":{"properties":{"action":{"description":"Storage rows: the CSX action (cached, evicted, persisted, read_closed, write_closed, ...); empty otherwise.","type":"string"},"action_id":{"type":"string"},"checkpoint_id":{"type":"string"},"cluster_id":{"type":"string"},"context":{"type":"string"},"description":{"type":"string"},"duration_ns":{"format":"int64","minimum":0,"type":"integer"},"failure_reason":{"type":"string"},"failure_stage":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"namespace":{"type":"string"},"node_name":{"type":"string"},"operation":{"type":"string"},"pause_ns":{"description":"Checkpoints: time the workload was held (see facts::checkpoint_pause_ns).","format":"int64","minimum":0,"type":"integer"},"physical_bytes":{"format":"int64","minimum":0,"type":"integer"},"pod_ready_at_ms":{"format":"int64","type":["integer","null"]},"pod_scheduled_at_ms":{"description":"Restores: PodScheduled / Ready transitions of the restored pod, once known.","format":"int64","type":["integer","null"]},"pod_uid":{"type":"string"},"read":{"type":"boolean"},"restore_uuid":{"type":"string"},"result":{"type":"string"},"storage_tier":{"type":"string"},"timestamp":{"type":"string"},"type":{"type":"string"},"workload_type":{"type":"string"},"write_target":{"description":"Write rows: where the write landed, tmpfs (the buffer) or nfs; empty otherwise.","type":"string"}},"required":["id","timestamp","type","operation","result","description","context","read","cluster_id","workload_type","node_name","pod_uid","name","namespace","action_id","checkpoint_id","restore_uuid","storage_tier","failure_stage","failure_reason","duration_ns","physical_bytes","pause_ns","action","write_target"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/events":{"get":{"operationId":"list_events","parameters":[{"description":"Time window in seconds (default: 3600)","in":"query","name":"time","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Time window in hours; takes precedence over `time`","in":"query","name":"hrs","required":false,"schema":{"format":"int32","type":["integer","null"]}},{"description":"Filter by operation: checkpoint, restore, storage (CSX tier movements) or all.\nWithout one, storage rows are left out so they cannot crowd checkpoint and restore results.","in":"query","name":"operation","required":false,"schema":{"type":["string","null"]}},{"description":"Filter by cluster","in":"query","name":"cluster_id","required":false,"schema":{"type":["string","null"]}},{"description":"Filter by workload: kubernetes or slurm","in":"query","name":"workload","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}},"description":"Recent operation results"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"ClickHouse unavailable"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Recent checkpoint and restore results, newest first (the UI notification feed)","tags":["Events"]}}}}
```