Skip to main content

​
Snapshots

A snapshot is a point-in-time copy of one volume:
Go to Storage → Snapshots and choose Create Snapshot, then pick the Volume and give it a Name. The volume’s own page has a Create Snapshot button that opens the same form with that volume already selected; it is disabled unless the volume is available or in_use.
1

Take it

Allowed against a volume in available or in_use — you do not have to detach to snapshot. The snapshot is created asynchronously (202, status creating).
2

Wait for available

Poll GET /v1/snapshots/{snapshot_id}. available means the snapshot is complete and can be restored from; error puts the reason in error_message.
A snapshot name is unique per volume, so nightly on two different volumes is fine. size_gb is the volume’s size frozen at the moment the snapshot was taken — the volume may have been extended since, so do not read it as the volume’s current size, and do not read it as the space the snapshot occupies.
Snapshotting an attached volume captures the device as it is at that instant, including anything the guest has buffered but not yet flushed. For a database or anything else with in-memory state, quiesce or flush inside the guest before taking the snapshot if you need it to be application-consistent.

​
Restoring from a snapshot

Restoring means creating a new volume from the snapshot. There is no in-place rollback:
On Create Volume, switch Source to From snapshot and choose the Snapshot. Size (GB) must be at least the snapshot’s size, and the Tier is yours to pick — a restore is not tied to the tier the source volume was on.Storage → Snapshots also has a Create volume from snapshot row action that opens the same form with the snapshot filled in.
The snapshot has to be available, and size_gb must be at least the snapshot’s frozen size — you can restore onto a larger volume, never a smaller one. The restored volume records source_snapshot_id, which is also what stops retention from reaping a snapshot something still depends on.

​
Snapshot policies

A policy is a schedule attached to one volume: take a snapshot every interval_minutes, then keep at most retention_count of the snapshots that policy created.
A schedule belongs to one volume, so it lives on that volume rather than in a list of its own. Open the volume, go to its Settings tab, and fill in the Snapshot schedule card: Name, Every (minutes), Keep, and optionally Also delete after (days). Choose Attach schedule.Once a schedule exists the card gains a switch that pauses it, and its buttons become Save and Remove schedule.
​
one policy per volume
required
Attaching a second policy to the same volume is a 409. Update the existing one instead.
​
1–43200
required
A minimum gap, not an exact cadence. A snapshot lands at or after the interval and never before, and can land a minute or two late when the scheduling pass is busy. The floor is one minute because that is how often the pass evaluates schedules; the ceiling is 30 days.
​
1–256
required
How many of this policy’s snapshots to keep. When a run takes the count past this, the oldest go first.
​
0–3650, default 0
An optional age bound applied on top of the count: a snapshot outside either window is reaped. 0 means no age bound.
The first snapshot lands one interval from now. Attaching a schedule is not itself a request for a snapshot — use POST /v1/snapshots if you want one immediately.
Scheduled snapshots are named <policy>-<UTC timestamp>, for example nightly-20260115T000000Z, and they inherit the policy’s tags so a listing tells you which schedule produced them without a second lookup.

​
What retention will never delete

A schedule is also an automatic deleter, so the limits on what it can remove matter more than the limits on what it keeps:

Snapshots you took by hand

Retention only matches snapshots carrying this policy’s snapshot_policy_id. A snapshot a person created has none and is never a candidate, whatever tags it has.

Snapshots something depends on

A snapshot a volume was created from — including a restore still running — is skipped and re-examined on a later run. It becomes reapable once the dependent volume is gone.

The single newest snapshot

The newest snapshot is exempt from the age bound. A volume that could not be snapshotted for longer than the window never loses its whole history that way.

Anything, while paused

enabled: false pauses the entire policy — no snapshots taken and none deleted. A paused schedule that kept reaping would delete history while you were looking at it.
Resuming a paused policy applies the retention window again on its next run. If you lowered retention_count while it was paused, everything now outside the window is reaped on that run.

​
Reading a schedule’s state

GET /v1/snapshot-policies/{policy_id} returns where the policy is in its cycle: last_error is the field to check on a schedule that has stopped producing snapshots — it carries reasons like an exhausted snapshots quota, or a volume that was mid-extend when the window came around. The Snapshot schedule card prints all three, so a stalled schedule can be read without leaving the console.
A missed window costs one snapshot, not one per window missed. next_run_at is re-stamped to now + interval_minutes each time the policy fires, never to previous + interval, so a schedule that could not run for six hours takes a single snapshot when it resumes rather than a catch-up burst. Changing interval_minutes re-bases the next run off now too, so shortening a daily schedule to hourly takes effect within the hour.
Deleting a policy detaches the schedule and keeps every snapshot it already took — they become ordinary snapshots you own outright and are never reaped again. Delete the snapshots themselves if that is what you meant.