Set snapshot retention

POST

snapshots

{id}

extend

curl --request POST \
  --url "https://api.bead.run/snapshots/$SNAPSHOT_ID/extend" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "retentionSeconds": 86400
}
JSON

{
  "snapshotID": "<string>",
  "templateID": "<string>",
  "buildID": "<string>",
  "status": "<string>",
  "name": "<string>",
  "names": [
    "<string>"
  ],
  "memoryRestored": true,
  "error": {},
  "remoteCopyStatus": "<string>",
  "sourceStatus": "<string>",
  "sourceBilling": "<string>",
  "sourceSandbox": {},
  "storageBoundBytes": {},
  "storageChargedUnits": 123,
  "retainUntilMs": {},
  "expiryWarningSeconds": 123,
  "storedBytes": {},
  "monthlyStorageUsd": {},
  "graceDeadlineMs": {},
  "graceState": "<string>",
  "preserved": true,
  "retryable": true,
  "nextAction": "<string>",
  "error_code": "<string>",
  "warnings": [
    {}
  ],
  "limit": {
    "limit": "<string>",
    "maximum": 123,
    "usage": 123,
    "next_action": "<string>",
    "reset_at": 123
  },
  "capture": {
    "sourcePreserved": true,
    "sourceBilling": "<string>",
    "capturedAtMs": 123,
    "freezeNanos": 123,
    "sourceResumed": true,
    "timing": {
      "incremental": true,
      "dirtyMemoryBytes": 123,
      "totalNanos": 123,
      "pauseNanos": 123,
      "dumpNanos": 123,
      "diskReflinkNanos": 123,
      "adoptNanos": 123,
      "cleanupNanos": 123,
      "resumeNanos": 123,
      "publicationNanos": 123
    }
  }
}

Authentication

Send your scoped bearer token in the Authorization: Bearer <BEAD_TOKEN> header, or send your API key in X-API-Key.

Parameters

string

required

Snapshot template identifier returned by capture.

Request body

The JSON body is required.

integer | null

Retention from now in seconds; null or omission clears scheduled expiry. Minimum: 60. May be null.

curl --request POST \
  --url "https://api.bead.run/snapshots/$SNAPSHOT_ID/extend" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "retentionSeconds": 86400
}
JSON

Response

200

Snapshot publication and storage status.

string

required

Snapshot identifier to poll or use as a template.

string

required

Template identifier for creating machines from this snapshot.

string

required

UUID of this immutable snapshot build.

string

required

Publication state; retired snapshots cannot create new machines.

string

required

Display name supplied for the snapshot.

string[]

required

Names associated with this snapshot.

boolean

required

Whether capture has reached the ready state.

string | null

required

Capture failure message, or null when no failure is recorded. May be null.

string

required

Status of the remote snapshot copy: ready, pending, or unavailable.

string

required

Current state of the source machine, including preserved when recovery is required.

string

required

Who funds the source machine: tenant, platform, or none.

string | null

required

Identifier of the machine captured by this snapshot. May be null.

integer | null

required

Maximum retained storage bytes authorized for this snapshot. May be null.

integer

required

Credit units debited for retained snapshot storage.

integer | null

required

Deletion deadline in Unix milliseconds; null means no scheduled expiry. May be null.

integer

required

Seconds before scheduled expiry when a warning is issued.

integer | null

required

Most recent confirmed physical storage byte count. May be null.

number | null

required

Estimated monthly storage charge for the confirmed bytes. May be null.

integer | null

required

End of storage credit grace in Unix milliseconds, or null when funded. May be null.

string

required

Storage funding state: funded, credit-grace, or deleted.

boolean

Whether the source machine is preserved for recovery.

boolean

Whether you can retry this failed capture.

string

Recommended source or snapshot recovery action.

string

Machine-readable capture error, such as admission_limit.

object[]

required

Storage grace and expiry warnings.

object

The resource limit that blocked the request.

Show Properties

string

required

Name of the exhausted resource.

integer

required

Allowed amount of this resource.

integer

required

Current usage counted against the limit.

string

required

Action you can take to proceed.

integer

Unix time in seconds when this time window resets.

object

Memory capture result and source recovery details.

Show Properties

boolean

required

Whether the source was preserved for recovery.

string

required

Who pays for the source after capture. Allowed values: "platform", "tenant".

integer

required

Capture timestamp in Unix milliseconds.

integer

required

Source freeze duration in nanoseconds.

boolean

required

Whether the source resumed after capture.

object

required

Time spent in each capture stage.

Show Properties

boolean

required

Whether this capture used an incremental memory dump.

integer

required

Allocated memory dump bytes before flattening.

integer

required

Total capture time in nanoseconds.

integer

required

Pause time in nanoseconds.

integer

required

Memory dump time in nanoseconds.

integer

required

Disk clone time in nanoseconds.

integer

required

Snapshot adoption time in nanoseconds.

integer

required

Cleanup time in nanoseconds.

integer

required

Source resume time in nanoseconds.

integer

required

Publication time in nanoseconds.

Errors

Status	Meaning
400	Invalid request values, unsupported bounds, or malformed JSON.
401	Authentication credential is missing or rejected.
402	Retained snapshot storage cannot be funded (`insufficient_credit` when prepaid balance is too low).
403	The credential lacks the required scope.
404	The requested resource does not exist or is outside your organization.
409	The snapshot storage state conflicts with the retention change.
413	Request body exceeds the route limit.
429	Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next_action and Retry-After when present.
503	Service or persistence is temporarily unavailable.

curl --request POST \
  --url "https://api.bead.run/snapshots/$SNAPSHOT_ID/extend" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "retentionSeconds": 86400
}
JSON

{
  "snapshotID": "<string>",
  "templateID": "<string>",
  "buildID": "<string>",
  "status": "<string>",
  "name": "<string>",
  "names": [
    "<string>"
  ],
  "memoryRestored": true,
  "error": {},
  "remoteCopyStatus": "<string>",
  "sourceStatus": "<string>",
  "sourceBilling": "<string>",
  "sourceSandbox": {},
  "storageBoundBytes": {},
  "storageChargedUnits": 123,
  "retainUntilMs": {},
  "expiryWarningSeconds": 123,
  "storedBytes": {},
  "monthlyStorageUsd": {},
  "graceDeadlineMs": {},
  "graceState": "<string>",
  "preserved": true,
  "retryable": true,
  "nextAction": "<string>",
  "error_code": "<string>",
  "warnings": [
    {}
  ],
  "limit": {
    "limit": "<string>",
    "maximum": 123,
    "usage": 123,
    "next_action": "<string>",
    "reset_at": 123
  },
  "capture": {
    "sourcePreserved": true,
    "sourceBilling": "<string>",
    "capturedAtMs": 123,
    "freezeNanos": 123,
    "sourceResumed": true,
    "timing": {
      "incremental": true,
      "dirtyMemoryBytes": 123,
      "totalNanos": 123,
      "pauseNanos": 123,
      "dumpNanos": 123,
      "diskReflinkNanos": 123,
      "adoptNanos": 123,
      "cleanupNanos": 123,
      "resumeNanos": 123,
      "publicationNanos": 123
    }
  }
}

Start here

Endpoints

Set snapshot retention

Authentication

Parameters

Request body

Response

200

Errors

​Authentication

​Parameters

​Request body

​Response

​200

​Errors

Authentication

Parameters

Request body

Response

200

Errors