Skip to main content
This feature is in public preview.
Events form an append-only log of what happens on your account, such as instances starting and terminating or orders filling. Only events from the last 7 days are available. Authenticate with a bearer token, as described in Using the API.
The response holds a page of events in data.
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. 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.
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.
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 for every parameter and response field.