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

# Events

> Read an ordered log of what happened on your account, from instances starting to orders filling

> [!NOTE]
>
> This feature is in [public preview](https://docs.sfcompute.com/preview/roadmap.md#feature-states).

Events form an append-only log of what happens on your account, such as
[instances](https://docs.sfcompute.com/preview/instances.md) starting and terminating or [orders](https://docs.sfcompute.com/preview/orders.md) filling. Only
events from the last 7 days are available. Authenticate with a bearer token, as described in
[Using the API](https://docs.sfcompute.com/preview/using-the-api.md).

```bash theme={null}
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events"
```

The response holds a page of events in `data`.

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_x7Kp2mQhTv9rWq3s",
      "cursor": "evtc_CWFjbWUtbGFicxRldnRfeDdLcDJtUWhUdjlyV3Ezc82ctrjWntufc7CGqIoN",
      "action": "instance.terminated",
      "occurred_at": 1755644312,
      "actor": { "type": "token", "id": "tokn_4Fq9Lr2XzT7mWc1KpV8sN" },
      "targets": [{ "type": "instance", "id": "inst_9dQpXk2LwZj" }]
    }
  ],
  "has_more": false,
  "cursor": "evtc_CWFjbWUtbGFicxRldnRfeDdLcDJtUWhUdjlyV3Ezc82ctrjWntufc7CGqIoN"
}
```

`action` names what happened, and `occurred_at` records when, as a Unix timestamp in seconds.
`actor` is the API token whose request caused the event, or `{ "type": "system" }` for automated
actions, such as a preemption or a scheduled end. `targets` lists the resources the event is about
as `{type, id}` pairs. Each `id` is the same ID the rest of the API uses for that resource.

## Event types

The table below lists the event types and their target types. To filter by resource, pass a target
type as `target_type` or a single resource's ID as `target`.

| Action | Target type | Meaning |
| - | - | - |
| `instance.created` | `instance` | The instance was created and is [awaiting allocation](https://docs.sfcompute.com/preview/instances.md#instance-lifecycle). |
| `instance.running` | `instance` | The instance started running. SSH access becomes available once its image finishes booting. |
| `instance.termination_imminent` | `instance` | The instance will be terminated soon because its allocation is ending, whether from preemption or a scheduled end. |
| `instance.terminated` | `instance` | The instance was terminated, whether by user request, replacement, preemption, or a scheduled end. |
| `instance.failed` | `instance` | The instance reported itself unhealthy. This does not terminate the instance, though work on it may be lost. [Replace](https://docs.sfcompute.com/preview/instances.md#replace-an-instance) or terminate it. |
| `instance.connection_lost` | `instance` | The instance stopped responding. |
| `order.created` | `order` | The order was placed. |
| `order.filled` | `order` | The order filled completely. |
| `order.cancelled` | `order` | The order was cancelled. |
| `image.published` | `image` | The image was published and is now publicly visible to all accounts. |
| `image.revoked` | `image` | The image was [revoked](https://docs.sfcompute.com/preview/images.md#revoking-an-image) and can no longer back new instances. |
| `image.reinstated` | `image` | The image was reinstated and can back new instances again. |
| `image.deprecated` | `image` | The image was [deprecated](https://docs.sfcompute.com/preview/images.md#image-lifecycle): it stops resolving by bare name, though an explicit pin can still launch it. |
| `trust_level.updated` | `account` | Your account's trust level changed. |
| `instance_sku_override.updated` | `instance_sku` | SF Compute set or changed property overrides on a [SKU](https://docs.sfcompute.com/preview/instance-skus.md) for your account. |
| `instance_sku_override.deleted` | `instance_sku` | SF Compute removed the property overrides on a SKU for your account. |

SF Compute adds new event types over time, so if you don't filter by `action`, expect actions that
aren't in this table.

## Following events from the CLI

`sf events list --follow` does the paging and polling for you and prints each new event as it
arrives. It accepts the `--action`, `--target`, `--target-type`, and `--since` filters.

```bash theme={null}
# Instance failures as they happen
sf events list --follow --action instance.failed

# One JSON object per line, for scripts
sf events list --follow --json

# Start an hour back, then keep following
sf events list --follow --since 1h
```

Without `--since`, `--follow` starts from now rather than replaying the whole 7-day window. When you
stop it with Ctrl-C, it prints a command to resume where it left off. With `--json`, it doesn't
print that command.

## Consuming the stream

List events with `GET /preview/v2/events`. Each request returns up to `limit` events, 50 by default
and at most 200.

To fetch the next page, pass the response's `cursor` back as `starting_after`. Paging this way never
skips an event. `has_more` tells you whether more events are already available.

The API lists events in the order they were recorded. Each instance's events are listed in the order
its changes happened, so `instance.created` comes before `instance.running`, and both come before
`instance.terminated`. An instance terminated while still awaiting allocation has no
`instance.running` event.

Across different resources, the list order can differ slightly from the order events happened in,
and an event's `occurred_at` can be earlier than the one before it. To resume reading later, save
the most recent cursor, not the latest `occurred_at`.

When `data` is empty and `has_more` is false, you have read everything so far. That response omits
`cursor`, so keep the one you sent and poll with it again later.

A new event usually appears within a few seconds, or later while a large update is in progress.

Filter with these query parameters.

* `action`: one exact event type
* `target`: one resource, by ID
* `target_type`: one type of resource
* `since` and `until`: inclusive bounds on `occurred_at`, as Unix timestamps

Filters combine, so a single request can ask for one event type on one resource. The list never goes
back more than 7 days, whatever `since` you pass.

```bash theme={null}
# Everything that happened to one instance
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?target=inst_9dQpXk2LwZj&target_type=instance"

# All terminations in the last 24 hours
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?action=instance.terminated&since=$(($(date +%s) - 86400))"

# When one order filled
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?action=order.filled&target=ordr_5Gh8kLm2Np4QwXz"
```

A cursor only works with the `action`, `target`, and `target_type` it was created with, and reusing
it with different ones returns 400 Bad Request. `since` and `until` can change between pages. If a
saved cursor falls outside the 7-day retention window, requests with it return 410 Gone. In that
case, start over without a cursor to read from the oldest available event.

## API reference

See the [Events API](https://docs.sfcompute.com/preview/api-reference/events/list-events.md) for every parameter and response
field.
