Snapshots

List snapshots

Every snapshot on the account that you can act on. Snapshots outlive the computers they came from, so this list routinely contains rows whose computer_id resolves to nothing — those carry orphaned: true, and clone is the operation that still works on them.

Uncertain fleet computer presence can require allow_partial=true even when snapshot rows were read; those rows carry computer_unreachable instead of a confirmed orphan status.

CAPTURES IN PROGRESS ARE LISTED TOO, and they are not snapshots yet. Such a row reads state: "capturing": restore, clone and delete all answer 404 on it until it lands. It carries the id the finished snapshot will have, which is what makes this endpoint the one you poll after POST /computers/:id/snapshots — the row you were handed there is this row, and it stops reading capturing in place rather than being replaced by something under another id. A capture appears exactly once: while it runs you get the placeholder, and from the moment the snapshot is stored you get the snapshot, never both.

CHECK state ON EVERY ROW, not on the newest one. This listing is a concatenation of one answer per host your computers are on, in a fixed host order that has nothing to do with time, so it carries no account-wide ordering to read anything from: a capture running on one host can appear after finished snapshots from another, and will do so consistently rather than intermittently.

Requires the viewer role or higher.

get/snapshots

Request

Base URL: https://app.mandala.computer/api/v1
URL: https://app.mandala.computer/api/v1/snapshots
Auth: HTTP bearer

Query parameters

allow_partial'1' | 'true'

Accept a listing known to be short. Without it this endpoint answers 503 when a hypervisor holding some of your things cannot be reached, because a short list is not a smaller truth — it reads exactly like the missing ones were deleted, and the obvious next thing a script does with something that has disappeared is tidy it up. A snapshot on a host that cannot be reached is listed as its id and unreachable: true, and nothing else; a key scoped to a workspace gets no such rows, only the short answer. A row whose source computer cannot be found for certain carries computer_unreachable: true and no orphaned.

include'unfinished'

Widen the listing to snapshots whose deletion began and has not finished — their state reads deleting. Left out by default because a half-deleted snapshot is not one you can restore or clone, so a bare listing is the set you can actually act on. Poll with it to learn when a deletion has finished: the row goes then.

Response

Your snapshots — every one you can act on, plus unfinished deletions if you asked for them.

idstring

computer_idstring

The computer these bytes came from. May name a computer that no longer exists.

computer_namestring

For a computer that still exists, its current name — so a rename is reflected without re-reading anything. For an orphan, the name at capture, which is all there is. Absent on snapshots taken before the daemon recorded it.

orphanedboolean

True when no host that answered lists the source computer, and every host that did not answer is one the platform’s records show holding none of this account’s computers. False when a host lists it. Omitted when that cannot be established, with computer_unreachable: true. Also omitted on the row DELETE /snapshots/{id} answers with, which does not work it out; read it from GET /snapshots.

computer_unreachableboolean

True when source computer presence cannot be established. Snapshot bytes may still be available; orphaned is omitted.

restore_availableboolean

The snapshot has a usable copy on the current source computer host. False for old-host copies; clone remains available when the snapshot itself is reachable.

namestring

kind'disk' | 'memory'

disk or memory.

state'capturing' | 'pending' | 'durable' | 'deleting'

Where these bytes have got to. capturing — the copy is still being taken, and this row is a placeholder rather than a snapshot: restore, clone and delete all 404 on it, though its id is already the id it will keep. pending — it is on the host and usable, and is being pushed to backup storage. durable — it is in backup storage too, which is the state your plan’s retention (GET /retention) ages out. deleting — a deletion began and has not finished, whether still under way or stalled; you only see these if you asked for them with include=unfinished.

Poll this after a capture, and wait for it to stop reading capturing rather than for it to read pending. pending is where a finished capture lands, but replication can carry it on to durable between two polls; both are states you can act on. A row that disappears without ever leaving capturing is a capture that failed.

A capture holds its computer until its upload to backup storage has finished, not just until it leaves capturing: a new capture of the SAME computer is refused (409, reason: "contention") while that upload runs, which is ordinarily for as long as this row reads pending, and is accepted once it reads durable. Restore, clone and delete all work from pending.

size_bytesinteger

created_atstring

RFC 3339 timestamp.

osstring

templatestring

cpuinteger

ram_mbinteger

disk_gbinteger

resolutionstring

The screen the capture was taken at, and what a clone of it comes up as.

autoboolean

Taken by the scheduler rather than by hand. Only these are ever aged out by your plan’s retention, and GET /retention is the window they are aged out on.

incrementalboolean

This snapshot is a link in a chain rather than a full copy, which is why it bills smaller.

unreachableboolean

As on Computer — a row from the placement cache, with nothing else on it.

Changes

No recorded changes to this operation across all 1 revision of this API.