sessions

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

Overview

Name	sessions
Type	Resource
Id	vercel.sandboxes.sessions

Fields

The following fields are returned by SELECT queries:

get

The session was retrieved successfully.

Name	Datatype	Description
id	string	The unique identifier of the sandbox. (example: sbx_123a6c5209bc3778245d011443644c8d27dc2c50)
project_id	string	The unique identifier of the project associated with this session. (example: prj_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: projectId)
source_snapshot_id	string	The unique identifier of the snapshot associated with this sandbox, if any. (example: snap_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: sourceSnapshotId)
source_sandbox_name	string	The name of the source sandbox. (example: my-sandbox) (wire: sourceSandboxName)
aborted_at	number	The time when the sandbox was aborted, in milliseconds since the epoch. (wire: abortedAt)
active_cpu_duration_ms	number	The amount of CPU time the sandbox consumed, if available, in milliseconds. This value is only available once the sandbox is stopped, and only if it stopped successfully. (wire: activeCpuDurationMs)
created_at	number	The time when the sandbox was created, in milliseconds since the epoch. (wire: createdAt)
cwd	string	The working directory of the sandbox. (example: /vercel/sandbox)
duration	number	The duration of the sandbox in milliseconds.
memory	number	Memory allocated to this sandbox in MB.
network_policy	object	The network policy applied to this sandbox, if any. (wire: networkPolicy)
network_transfer	object	The quantity of data transfered to and from the sandbox, in bytes. This value is only available once the sandbox is stopped, and only if it stopped successfully. (wire: networkTransfer)
region	string	The region where the sandbox is hosted. (example: iad1)
requested_at	number	The time when the sandbox was requested, in milliseconds since the epoch. (wire: requestedAt)
requested_stop_at	number	The time when the sandbox was requested to stop, in milliseconds since the epoch. (wire: requestedStopAt)
runtime	string	The runtime of the sandbox. (example: node22)
snapshotted_at	number	The time when a snapshot was requested, in milliseconds since the epoch. (wire: snapshottedAt)
started_at	number	The time when the sandbox was started, in milliseconds since the epoch. (wire: startedAt)
status	string	The status of the sandbox. (aborted, failed, pending, running, snapshotting, stopped, stopping) (example: running)
stopped_at	number	The time when the sandbox was stopped, in milliseconds since the epoch. (wire: stoppedAt)
timeout	number	The maximum amount of time the sandbox will run for in milliseconds.
updated_at	number	The last time the sandbox was updated, in milliseconds since the epoch. (wire: updatedAt)
vcpus	number	Number of vCPUs allocated to this sandbox.

list

The list of sessions matching the request filters.

Name	Datatype	Description
id	string	The unique identifier of the sandbox. (example: sbx_123a6c5209bc3778245d011443644c8d27dc2c50)
project_id	string	The unique identifier of the project associated with this session. (example: prj_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: projectId)
source_snapshot_id	string	The unique identifier of the snapshot associated with this sandbox, if any. (example: snap_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: sourceSnapshotId)
source_sandbox_name	string	The name of the source sandbox. (example: my-sandbox) (wire: sourceSandboxName)
aborted_at	number	The time when the sandbox was aborted, in milliseconds since the epoch. (wire: abortedAt)
active_cpu_duration_ms	number	The amount of CPU time the sandbox consumed, if available, in milliseconds. This value is only available once the sandbox is stopped, and only if it stopped successfully. (wire: activeCpuDurationMs)
created_at	number	The time when the sandbox was created, in milliseconds since the epoch. (wire: createdAt)
cwd	string	The working directory of the sandbox. (example: /vercel/sandbox)
duration	number	The duration of the sandbox in milliseconds.
memory	number	Memory allocated to this sandbox in MB.
network_policy	object	The network policy applied to this sandbox, if any. (wire: networkPolicy)
network_transfer	object	The quantity of data transfered to and from the sandbox, in bytes. This value is only available once the sandbox is stopped, and only if it stopped successfully. (wire: networkTransfer)
region	string	The region where the sandbox is hosted. (example: iad1)
requested_at	number	The time when the sandbox was requested, in milliseconds since the epoch. (wire: requestedAt)
requested_stop_at	number	The time when the sandbox was requested to stop, in milliseconds since the epoch. (wire: requestedStopAt)
runtime	string	The runtime of the sandbox. (example: node22)
snapshotted_at	number	The time when a snapshot was requested, in milliseconds since the epoch. (wire: snapshottedAt)
started_at	number	The time when the sandbox was started, in milliseconds since the epoch. (wire: startedAt)
status	string	The status of the sandbox. (aborted, failed, pending, running, snapshotting, stopped, stopping) (example: running)
stopped_at	number	The time when the sandbox was stopped, in milliseconds since the epoch. (wire: stoppedAt)
timeout	number	The maximum amount of time the sandbox will run for in milliseconds.
updated_at	number	The last time the sandbox was updated, in milliseconds since the epoch. (wire: updatedAt)
vcpus	number	Number of vCPUs allocated to this sandbox.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	session_id	team_id, slug	Retrieves detailed information about a specific session, including its current status, resource configuration, and exposed routes.
list	select		project, name, limit, cursor, sort_order, team_id, slug	Retrieves a paginated list of sessions belonging to a specific sandbox. Results are sorted by creation time and paginated using an opaque cursor.
stop	exec	session_id	teamId, slug	Stops a running session and releases its allocated resources. All running processes within the session will be terminated. This action cannot be undone. A stopped session cannot be restarted.
extend_timeout	exec	session_id, duration	teamId, slug	Extends the maximum execution time of a running session. The session must be active and able to accept commands. The total timeout cannot exceed the maximum allowed limit for your account.
update_network_policy	exec	session_id, mode	teamId, slug	Replaces the network access policy of a running session. Use this to control which external hosts the session can communicate with. This is a full replacement. Any previously configured network rules will be overwritten.

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 update the network policy for.
cursor	string	Opaque pagination cursor from a previous response.
limit	number	Maximum number of sessions to return in the response. Used for pagination.
name	string	Filter sessions by sandbox name. Only sessions belonging to the specified sandbox are returned.
project	string	The unique identifier or name of the project to list sessions 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 session, including its current status, resource configuration, and exposed routes.

SELECT
id,
project_id,
source_snapshot_id,
source_sandbox_name,
aborted_at,
active_cpu_duration_ms,
created_at,
cwd,
duration,
memory,
network_policy,
network_transfer,
region,
requested_at,
requested_stop_at,
runtime,
snapshotted_at,
started_at,
status,
stopped_at,
timeout,
updated_at,
vcpus
FROM vercel.sandboxes.sessions
WHERE session_id = '{{ session_id }}' -- required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

list

Retrieves a paginated list of sessions belonging to a specific sandbox. Results are sorted by creation time and paginated using an opaque cursor.

SELECT
id,
project_id,
source_snapshot_id,
source_sandbox_name,
aborted_at,
active_cpu_duration_ms,
created_at,
cwd,
duration,
memory,
network_policy,
network_transfer,
region,
requested_at,
requested_stop_at,
runtime,
snapshotted_at,
started_at,
status,
stopped_at,
timeout,
updated_at,
vcpus
FROM vercel.sandboxes.sessions
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 }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

stop

Stops a running session and releases its allocated resources. All running processes within the session will be terminated. This action cannot be undone. A stopped session cannot be restarted.

EXEC vercel.sandboxes.sessions.stop 
@session_id='{{ session_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}'
;

extend_timeout

Extends the maximum execution time of a running session. The session must be active and able to accept commands. The total timeout cannot exceed the maximum allowed limit for your account.

EXEC vercel.sandboxes.sessions.extend_timeout 
@session_id='{{ session_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"duration": {{ duration }}
}'
;

update_network_policy

Replaces the network access policy of a running session. Use this to control which external hosts the session can communicate with. This is a full replacement. Any previously configured network rules will be overwritten.

EXEC vercel.sandboxes.sessions.update_network_policy 
@session_id='{{ session_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"mode": "{{ mode }}", 
"allowedDomains": "{{ allowedDomains }}", 
"allowedCIDRs": "{{ allowedCIDRs }}", 
"deniedCIDRs": "{{ deniedCIDRs }}", 
"injectionRules": "{{ injectionRules }}", 
"allow": "{{ allow }}", 
"subnets": "{{ subnets }}"
}'
;