snapshots

Creates, updates, deletes, gets or lists a snapshots resource.

Overview

Name	snapshots
Type	Resource
Id	vercel.sandboxes.snapshots

Fields

The following fields are returned by SELECT queries:

get

This object contains information related to a Snapshot of a Vercel Sandbox session (v2 API).

Name	Datatype	Description
id	string	The unique identifier of the snapshot. (example: snap_123a6c5209bc3778245d011443644c8d27dc2c50)
parent_id	string	The unique identifier of the parent snapshot, if this snapshot was created from another snapshot. (example: snap_parent123) (wire: parentId)
source_session_id	string	The unique identifier of the session from which the snapshot was created. (example: sbx_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: sourceSessionId)
created_at	number	The time when the snapshot was created, in milliseconds since the epoch. (wire: createdAt)
creation_method	string	The method used to create the snapshot. (automatic, manual) (example: manual) (wire: creationMethod)
expires_at	number	The time when the snapshot will expire, in milliseconds since the epoch. If not set, the snapshot does not have any expiration. (wire: expiresAt)
last_used_at	number	The last time the snapshot was used (e.g. to resume or create a sandbox), in milliseconds since the epoch. Falls back to createdAt for older snapshots that predate this field. (wire: lastUsedAt)
region	string	The region where the snapshot is stored. (example: iad1)
regions	array	The regions where the snapshot is available.
size_bytes	number	The size of the snapshot in bytes. (wire: sizeBytes)
status	string	The status of the snapshot. (created, deleted, failed) (example: created)
updated_at	number	The last time the snapshot was updated, in milliseconds since the epoch. (wire: updatedAt)

list

This object contains information related to a Snapshot of a Vercel Sandbox session (v2 API).

Name	Datatype	Description
id	string	The unique identifier of the snapshot. (example: snap_123a6c5209bc3778245d011443644c8d27dc2c50)
parent_id	string	The unique identifier of the parent snapshot, if this snapshot was created from another snapshot. (example: snap_parent123) (wire: parentId)
source_session_id	string	The unique identifier of the session from which the snapshot was created. (example: sbx_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: sourceSessionId)
created_at	number	The time when the snapshot was created, in milliseconds since the epoch. (wire: createdAt)
creation_method	string	The method used to create the snapshot. (automatic, manual) (example: manual) (wire: creationMethod)
expires_at	number	The time when the snapshot will expire, in milliseconds since the epoch. If not set, the snapshot does not have any expiration. (wire: expiresAt)
last_used_at	number	The last time the snapshot was used (e.g. to resume or create a sandbox), in milliseconds since the epoch. Falls back to createdAt for older snapshots that predate this field. (wire: lastUsedAt)
region	string	The region where the snapshot is stored. (example: iad1)
regions	array	The regions where the snapshot is available.
size_bytes	number	The size of the snapshot in bytes. (wire: sizeBytes)
status	string	The status of the snapshot. (created, deleted, failed) (example: created)
updated_at	number	The last time the snapshot was updated, in milliseconds since the epoch. (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	snapshot_id	team_id, slug	Retrieves detailed information about a specific snapshot, including its creation time, size, expiration date, and the source session it was created from.
list	select		project, name, limit, cursor, sort_order, team_id, slug	Retrieves a paginated list of snapshots for a specific project.
create	insert	session_id	team_id, slug	Creates a point-in-time snapshot of a running session's filesystem. Snapshots can be used to quickly restore a session to a previous state or to create new sessions with pre-configured environments. The session must be running and able to accept commands for a snapshot to be created. The session will be terminated after the snapshot is created. Unlike v2, snapshots expire after 7 days when neither the request nor the sandbox configuration specifies an expiration.
delete	delete	snapshot_id	team_id, slug	Permanently deletes a snapshot and frees its associated storage. This action cannot be undone. After deletion, the snapshot can no longer be used to create new sessions.
create_v2	exec	session_id	teamId, slug	Creates a point-in-time snapshot of a running session's filesystem. Snapshots can be used to quickly restore a session to a previous state or to create new sessions with pre-configured environments. The session must be running and able to accept commands for a snapshot to be created. The session will be terminated after the snapshot is created.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
session_id	string	The unique identifier of the session to snapshot.
snapshot_id	string	The unique identifier of the snapshot to delete.
cursor	string	Opaque pagination cursor from a previous response.
limit	number	Maximum number of snapshots to return in the response. Used for pagination.
name	string	Name for the sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores).
project	string	The unique identifier or name of the project to list snapshots for.
slug	string	The Team slug to perform the request on behalf of.
sort_order	string	Sort direction for results by creation time. (wire: sortOrder)
teamId	string	The Team identifier to perform the request on behalf of.
team_id	string	The Team identifier to perform the request on behalf of. (wire: teamId)

SELECT examples

get

Retrieves detailed information about a specific snapshot, including its creation time, size, expiration date, and the source session it was created from.

SELECT
id,
parent_id,
source_session_id,
created_at,
creation_method,
expires_at,
last_used_at,
region,
regions,
size_bytes,
status,
updated_at
FROM vercel.sandboxes.snapshots
WHERE snapshot_id = '{{ snapshot_id }}' -- required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

list

Retrieves a paginated list of snapshots for a specific project.

SELECT
id,
parent_id,
source_session_id,
created_at,
creation_method,
expires_at,
last_used_at,
region,
regions,
size_bytes,
status,
updated_at
FROM vercel.sandboxes.snapshots
WHERE project = '{{ project }}'
AND name = '{{ name }}'
AND limit = '{{ limit }}'
AND cursor = '{{ cursor }}'
AND sort_order = '{{ sort_order }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

INSERT examples

create

Creates a point-in-time snapshot of a running session's filesystem. Snapshots can be used to quickly restore a session to a previous state or to create new sessions with pre-configured environments. The session must be running and able to accept commands for a snapshot to be created. The session will be terminated after the snapshot is created. Unlike v2, snapshots expire after 7 days when neither the request nor the sandbox configuration specifies an expiration.

INSERT INTO vercel.sandboxes.snapshots (
expiration,
session_id,
team_id,
slug
)
SELECT 
{{ expiration }},
'{{ session_id }}',
'{{ team_id }}',
'{{ slug }}'
RETURNING
session,
snapshot
;

Manifest

# Description fields are for documentation purposes
- name: snapshots
props:
  - name: session_id
    value: "{{ session_id }}"
    description: Required parameter for the snapshots resource.
  - name: expiration
    value: {{ expiration }}
    description: |
      The number of milliseconds after which the snapshot will expire and be deleted. Defaults to 7 days when neither this field nor the sandbox configuration specifies an expiration. Use 0 for no expiration.
  - name: team_id
    value: "{{ team_id }}"
    description: The Team identifier to perform the request on behalf of.
    description: The Team identifier to perform the request on behalf of.
  - name: slug
    value: "{{ slug }}"
    description: The Team slug to perform the request on behalf of.
    description: The Team slug to perform the request on behalf of.

DELETE examples

delete

Permanently deletes a snapshot and frees its associated storage. This action cannot be undone. After deletion, the snapshot can no longer be used to create new sessions.

DELETE FROM vercel.sandboxes.snapshots
WHERE snapshot_id = '{{ snapshot_id }}' --required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

create_v2

Creates a point-in-time snapshot of a running session's filesystem. Snapshots can be used to quickly restore a session to a previous state or to create new sessions with pre-configured environments. The session must be running and able to accept commands for a snapshot to be created. The session will be terminated after the snapshot is created.

EXEC vercel.sandboxes.snapshots.create_v2 
@session_id='{{ session_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"expiration": {{ expiration }}
}'
;