v33

latestOpenAPI 3.1.0raw.githubusercontent.com2026-04-175267122.5 KB

Create or update snapshot schedule for an instance

Scheduled runs automatically choose snapshot behavior from current instance state:

Running or Standby source: create a Standby snapshot.
Stopped source: create a Stopped snapshot. For running instances, this includes a brief pause/resume cycle during each capture. The minimum supported interval is 1m, but larger intervals are recommended for heavier or latency-sensitive workloads. Updating only retention, metadata, or name_prefix preserves the next scheduled run; changing interval establishes a new cadence.

put/instances/{id}/snapshot-schedule

Path parameters

idstring required

Source instance ID or name

Request body

intervalstring required

Snapshot interval (Go duration format, minimum 1m).

name_prefixstring nullable

Optional prefix for auto-generated scheduled snapshot names (max 47 chars).

metadataTags

User-defined key-value tags.

Example request

{
  "interval": "24h",
  "name_prefix": "nightly",
  "metadata": {
    "team": "backend",
    "env": "staging"
  },
  "retention": {
    "max_count": 7,
    "max_age": "168h"
  }
}

Response

Snapshot schedule updated

instance_idstring required

Source instance ID.

intervalstring required

Snapshot interval (Go duration format).

name_prefixstring nullable

Optional prefix used for generated scheduled snapshot names.

metadataTags

User-defined key-value tags.

next_run_atstring date-time required

Next scheduled run time.

last_run_atstring date-time nullable

Last schedule execution time.

last_snapshot_idstring nullable

Snapshot ID produced by the last successful run.

last_errorstring nullable

Last schedule run error, if any.

created_atstring date-time required

Schedule creation timestamp.

updated_atstring date-time required

Schedule update timestamp.

Example response

{
  "instance_id": "qilviffnqzck2jrim1x6s2b1",
  "interval": "24h",
  "name_prefix": "nightly",
  "metadata": {
    "team": "backend",
    "env": "staging"
  },
  "retention": {
    "max_count": 7,
    "max_age": "168h"
  },
  "next_run_at": "2026-03-10T02:00:00Z",
  "last_run_at": "2026-03-09T02:00:00Z",
  "last_snapshot_id": "q7z1w7l2af4l8y7q1h7g2m3s",
  "last_error": "invalid state transition: stopped snapshot requires source in Stopped, got Running",
  "created_at": "2026-03-09T01:00:00Z",
  "updated_at": "2026-03-09T01:30:00Z"
}