Sandboxes

List all sandboxes

Returns sandboxes belonging to the authenticated team, ordered by creation time (newest first) by default.

Pagination, sorting, and search

Pass limit (and offset) to fetch one page at a time; the X-Total-Count response header reports the total across all pages. Omitting limit returns the full list, so existing unpaginated callers are unaffected. Sort with sort + order, filter by exact status, and search names with q (case-insensitive substring).

Filtering by metadata

Any query parameter prefixed metadata. is treated as a filter clause: ?metadata.env=prod&metadata.owner=agent-7. Multiple filters AND together — a sandbox matches only if every key/value pair is present in its metadata. Values are compared as exact strings; there is no type coercion or substring matching.

GET

sandboxes

List all sandboxes

curl --request GET \
  --url https://api.superserve.ai/sandboxes \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.superserve.ai/sandboxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.superserve.ai/sandboxes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.superserve.ai/sandboxes"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.superserve.ai/sandboxes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

[
  {
    "id": "<string>",
    "name": "<string>",
    "vcpu_count": 123,
    "memory_mib": 123,
    "snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "timeout_seconds": 123,
    "auto_delete_seconds": 123,
    "auto_delete_at": "2023-11-07T05:31:56Z",
    "network": {
      "allow_out": [
        "api.openai.com",
        "*.github.com",
        "8.8.8.8/32"
      ],
      "deny_out": [
        "0.0.0.0/0"
      ]
    },
    "metadata": {
      "env": "prod",
      "owner": "agent-7"
    }
  }
]

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

X-API-Key

string

header

required

Query Parameters

metadata.{key}

string

Filter sandboxes whose metadata contains an exact {key}: <value> pair. Repeat with different keys to AND multiple filters. Values are always strings. Example: ?metadata.env=prod.

string

Case-insensitive substring match on the resource name.

status

enum<string>

Filter by exact sandbox status. Unknown values are a 400.

Available options:

starting,

active,

pausing,

paused,

resuming,

failed,

deleted

sort

enum<string>

default:created_at

Column to sort by (paired with order).

Available options:

created_at,

name,

status

order

enum<string>

default:desc

Sort direction applied to sort.

Available options:

asc,

desc

limit

integer

Maximum rows to return (page size). Omit to return the full list unpaginated — the default, preserved for backward compatibility with callers that page client-side. Values above 200 are clamped to 200.

Required range: 1 <= x <= 200

offset

integer

default:0

Rows to skip before the page. Combine with limit to paginate.

Required range: x >= 0

Response

List of sandboxes belonging to the authenticated team

string

Public sandbox ID: a bare UUID, or the region-tagged form sb-<region>-<uuid> (e.g. sb-use-1b4e28ba-…). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably.

Pattern: ^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

name

string

status

enum<string>

Current state of the sandbox. active means running; paused means paused and awaiting resume. resuming is a transient state observed while the platform restores a paused sandbox (e.g. via auto-resume on /exec); clients should retry shortly.

Available options:

active,

paused,

resuming

vcpu_count

integer

memory_mib

integer

snapshot_id

string<uuid>

ID of the latest snapshot (present after a pause).

created_at

string<date-time>

timeout_seconds

integer<int32>

Auto-pause timeout in seconds, if configured. Absent when auto-pause is disabled.

auto_delete_seconds

integer<int32>

Garbage-collection window for the paused state, if configured. Absent when auto-delete is disabled.

auto_delete_at

string<date-time>

When the sandbox will be deleted. Present only while the sandbox is paused with auto_delete_seconds configured. The deadline is armed when the sandbox pauses (or when the setting is applied to an already-paused sandbox) and cleared on resume.

network

object

Current egress allow/deny rules, if any have been configured. Absent when the sandbox uses default network settings.

Show child attributes

metadata

object

User-supplied tags attached at creation. Always present — sandboxes created without metadata return {} rather than being absent.

Show child attributes

Example:

{ "env": "prod", "owner": "agent-7" }

preview_access

enum<string>

Default access for newly published ports. public and private are strict modes; existing published rows keep their own access. legacy_public may be returned for an older sandbox and preserves all-port behavior until updated to a strict mode.

Available options:

legacy_public,

public,

private

List all sandboxes

curl --request GET \
  --url https://api.superserve.ai/sandboxes \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.superserve.ai/sandboxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.superserve.ai/sandboxes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.superserve.ai/sandboxes"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.superserve.ai/sandboxes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

[
  {
    "id": "<string>",
    "name": "<string>",
    "vcpu_count": 123,
    "memory_mib": 123,
    "snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "timeout_seconds": 123,
    "auto_delete_seconds": 123,
    "auto_delete_at": "2023-11-07T05:31:56Z",
    "network": {
      "allow_out": [
        "api.openai.com",
        "*.github.com",
        "8.8.8.8/32"
      ],
      "deny_out": [
        "0.0.0.0/0"
      ]
    },
    "metadata": {
      "env": "prod",
      "owner": "agent-7"
    }
  }
]

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Sandboxes

Exec

Files

Templates

Secrets

Billing

Team Management

Activity

List all sandboxes

Pagination, sorting, and search

Filtering by metadata

Authorizations

Query Parameters

Response