---
title: "Create or update snapshot schedule for an instance"
method: PUT
path: "/instances/{id}/snapshot-schedule"
---

# Create or update snapshot schedule for an instance

`PUT /instances/{id}/snapshot-schedule`

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.

## Path parameters

- `id` string, required

## Request body

- SetSnapshotScheduleRequest
  - `interval` string, required — Snapshot interval (Go duration format, minimum 1m).
  - `name_prefix` string, nullable — Optional prefix for auto-generated scheduled snapshot names (max 47 chars).
  - `metadata` Tags — User-defined key-value tags.
  - `retention` SnapshotScheduleRetention, required — Automatic cleanup policy for scheduled snapshots.
    - `max_count` integer — Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).
    - `max_age` string — Delete scheduled snapshots older than this duration (Go duration format).

## Response `200`

Snapshot schedule updated

- SnapshotSchedule
  - `instance_id` string, required — Source instance ID.
  - `interval` string, required — Snapshot interval (Go duration format).
  - `name_prefix` string, nullable — Optional prefix used for generated scheduled snapshot names.
  - `metadata` Tags — User-defined key-value tags.
  - `retention` SnapshotScheduleRetention, required — Automatic cleanup policy for scheduled snapshots.
    - `max_count` integer — Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).
    - `max_age` string — Delete scheduled snapshots older than this duration (Go duration format).
  - `next_run_at` string, date-time, required — Next scheduled run time.
  - `last_run_at` string, date-time, nullable — Last schedule execution time.
  - `last_snapshot_id` string, nullable — Snapshot ID produced by the last successful run.
  - `last_error` string, nullable — Last schedule run error, if any.
  - `created_at` string, date-time, required — Schedule creation timestamp.
  - `updated_at` string, date-time, required — Schedule update timestamp.

## Other responses

- `400` — Bad request - invalid schedule request
- `404` — Instance not found
- `500` — Internal server error

---

[API](https://skmtc.net/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.net/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/hypeman-api/versions/b4642bb950dc/schema)