Audit events

Audit events tell you who or what changed an instance. Every vm.state_change and vm.start_failed event carries an attribution that names its source, such as an API request, the guest, or scale-to-zero, and the user behind an API request. You can subscribe to these events as a live stream.

Use the stream to:

• Keep an audit trail of who changed what.
• Alert on specific causes, such as an instance that ran out of quota.
• Follow instance changes as they happen, without polling the API.

Subscribing to the stream

Open a GET request on /v1/audit. The response is a server-sent events stream that stays open and delivers each event as it happens:

Any valid API token can subscribe. The stream only delivers events for instances that your account owns, and that still holds after you delete the instance.

The stream starts empty and only carries events that happen after you connect. When nothing happens for 30 seconds, the platform sends a : heartbeat comment line to keep the connection alive. Event stream clients ignore comment lines.

Filtering events

Three optional query parameters narrow down the stream. Each takes a comma-separated list:

An event has to match every parameter you set. A parameter you leave out, or leave empty, matches everything. If you repeat a parameter, the last one wins.

For example, to follow the state changes of all instances tagged prod:

And to follow two specific instances:

The platform answers with 400 Bad Request for an unknown parameter, an invalid UUID or tag, or a request that carries a body. The same goes for an unknown event type, or one the stream doesn't carry such as vm.annotate. It answers with 429 Too Many Requests when the controller already holds its limit of subscriptions.

Event format

Each event arrives as an event: line with its type, followed by a data: line with a JSON document, and a blank line:

Code
event: vm.state_change
data: {"type":"vm.state_change","timestamp":"2026-09-28T10:01:22.306418204Z", ...}

Here is the full document of an API request that stopped an instance:

Code
{
  "type": "vm.state_change",
  "timestamp": "2026-09-28T10:01:22.347105522Z",
  "object": {
    "type": "i",
    "uuid": "186ac04c-6ede-46eb-b559-7d6a97792e6b",
    "owner": "242e0044-7918-462b-b4c7-d3edf94517a4",
    "tags": ["audit-test"]
  },
  "attribution": {
    "operation": "61fbce49-8a0e-4f5b-9a3c-0d2c7e81f6a4",
    "kind": "stop",
    "trigger": "observed",
    "origin": "api",
    "user": "242e0044-7918-462b-b4c7-d3edf94517a4"
  },
  "data": {
    "prev": "stopping",
    "new": "stopped",
    "stop": {
      "reason": ["sys-exit", "app-exit", "ukpd", "api"],
      "code": 33024,
      "exit_code": 1
    }
  }
}

A document leaves out a field that has no value, rather than setting it to null.

Event types

vm.state_change

The platform sends vm.state_change whenever an instance moves to a different state. data.prev and data.new hold the old and the new state:

An instance also changes between stopped and standby when only its autostart setting changes.

When an instance comes to rest in stopped or standby, data.stop tells why it stopped. See stop information.

vm.start_failed

The platform sends vm.start_failed when a start doesn't happen, for example because the start would exceed a quota.

Code
{
  "type": "vm.start_failed",
  "timestamp": "2026-09-28T10:12:40.118302951Z",
  "object": { "type": "i", "uuid": "...", "owner": "..." },
  "attribution": { "operation": "...", "kind": "start", "trigger": "requested", "origin": "api", "user": "..." },
  "data": {
    "state": "stopped",
    "error": "EDQUOT",
    "stop": { "reason": ["ukpd"], "cause": "quota-exceeded" }
  }
}

data.state holds the state the instance stays in, and data.error names the error. data.stop tells why, if the platform had already recorded a cause. A start that the platform turns down before it changes anything produces no vm.state_change.

Stop information

data.stop describes why an instance stopped. It holds the same information as the stop reason of the instances API, with names in place of bits:

Attribution

attribution names who or what caused a change:

Following an operation

One action often causes more than one state change. They all share the same operation, so you can group them. The first one has the trigger requested, and the rest have observed.

Stopping an instance through the API gives two events:

Code
running  → stopping   origin=api  kind=stop  trigger=requested  operation=61fbce49…
stopping → stopped    origin=api  kind=stop  trigger=observed   operation=61fbce49…

An instance with scale-to-zero that goes idle, and then wakes up for an incoming request, gives two operations:

Code
running  → stopping   origin=scale-to-zero  kind=stop   trigger=requested  operation=9d955682…
stopping → standby    origin=scale-to-zero  kind=stop   trigger=observed   operation=9d955682…
standby  → starting   origin=proxy          kind=start  trigger=requested  operation=11b15061…
starting → running    origin=proxy          kind=start  trigger=observed   operation=11b15061…

A change that the platform can't match to an operation carries the origin system and no operation.

Missed events

If your client falls behind the stream, the platform drops the oldest events it holds for you, and sends a gap event in their place:

Code
event: gap
data: {"dropped":12}

After a gap, read the current state of the instances you follow from the instances API, since the stream no longer holds the whole history.

Changes from earlier releases

The same state change before and after release 14:

Code
{
  "type": "vm.state_change",
  "timestamp": "2026-09-28T10:01:02.873148018Z",
  "object": { "type": "i", "uuid": "186ac04c-6ede-46eb-b559-7d6a97792e6b", "owner": "242e0044-7918-462b-b4c7-d3edf94517a4" },
  "attribution": { "operation": "2990b90d-6f27-411b-bca4-5e26f6b8ab94", "kind": "start", "trigger": "observed", "origin": "api", "user": "242e0044-7918-462b-b4c7-d3edf94517a4" },
  "data": { "prev": "starting", "new": "running" }
}

Limitations

• A controller accepts at most 64 subscriptions at a time, across all users. Beyond that, a new subscription fails until another one closes.
• The stream doesn't replay older events.
• Through the public API endpoint, the stream needs the proxy configuration of release 14.
• The only audit events are vm.state_change and vm.start_failed, alongside the gap control event. Creating or deleting an instance has no event of its own, and you can't subscribe to vm.annotate.
• A restart through the CLI shows up as a stop operation followed by a start operation, not as one restart operation.
• Autokill after a set count of requests shows up with the origin proxy.

Learn more

• Metrics: runtime statistics for your instances.
• Instances: instance states and lifecycle.
• Tagging: label instances to filter the stream.
• Scale-to-zero and autokill: the platform features that change instance state on their own.
• Annotations: the vm.annotate event in the node event log.
• Unikraft Cloud's REST API reference.