List Sandboxes
curl --request GET \
--url https://api.declaw.ai/sandboxes \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.declaw.ai/sandboxes"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.declaw.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.declaw.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.declaw.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))
}HttpResponse<String> response = Unirest.get("https://api.declaw.ai/sandboxes")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.declaw.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{
"sandboxes": [
{}
],
"total": 123,
"next_token": {}
}Sandbox API
List Sandboxes
Return the sandboxes visible to the authenticated API key, filtered and paged.
GET
/
sandboxes
List Sandboxes
curl --request GET \
--url https://api.declaw.ai/sandboxes \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.declaw.ai/sandboxes"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.declaw.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.declaw.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.declaw.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))
}HttpResponse<String> response = Unirest.get("https://api.declaw.ai/sandboxes")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.declaw.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{
"sandboxes": [
{}
],
"total": 123,
"next_token": {}
}Returns the sandboxes owned by the authenticated API key, newest first. Killed
sandboxes are left out unless
state asks for them. Results come in a
sandboxes array, with the total that match and a next_token while more
pages remain.
Query Parameters
string
States to list:
live, paused, killed, or all. Repeat the parameter or
separate values with commas to list several (?state=live&state=paused,
?state=paused,killed). running is accepted as live, and creating,
which no sandbox is ever reported in, lists none. Omit it to list every state
but killed. An unknown state is refused with 400.string
Lists only sandboxes whose metadata holds every given key with exactly the
given value. Send a JSON object of strings (
{"user":"u1"}) or key=value
pairs joined by & (user=u1&env=prod), URL-encoded as the parameter’s
value. In the key=value form, URL-encode each key and value first, as in a
query string: an unencoded + reads as a space. A filter that can’t be read
is refused with 400 rather than ignored.integer
default:"100"
Page size. Capped at
1000.string
The
next_token of the previous page, to fetch the page after it. Send the
same filters with it.integer
default:"0"
Matching sandboxes to skip. Ignored when
next_token is sent. Prefer
next_token: offsets shift when sandboxes are created or killed between
pages, so a page can repeat or skip one.Response
integer
How many sandboxes match the filters, across all pages.
string | null
Cursor for the next page.
null on the last page.Example
curl -G https://api.declaw.ai/sandboxes \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode 'metadata={"user":"u1"}' \
--data-urlencode 'state=live,paused' \
--data-urlencode 'limit=2'
from declaw import Sandbox, SandboxQuery
query = SandboxQuery(metadata={"user": "u1"})
token = None
while True:
page = Sandbox.list(query=query, limit=50, next_token=token,
api_key="YOUR_API_KEY", domain="api.declaw.ai")
for sbx in page["sandboxes"]:
print(sbx["sandbox_id"], sbx["state"])
token = page["next_token"]
if not token:
break
import { Sandbox } from "@declaw/sdk";
let nextToken: string | undefined;
do {
const page = await Sandbox.list({
query: { metadata: JSON.stringify({ user: "u1" }) },
limit: 50,
nextToken,
apiKey: "YOUR_API_KEY",
domain: "api.declaw.ai",
});
for (const sbx of page.sandboxes) {
console.log(sbx.sandboxId, sbx.state);
}
nextToken = page.nextToken;
} while (nextToken);
Response
{
"sandboxes": [
{
"sandbox_id": "sbx-a1b2c3d4",
"template_id": "tpl-base",
"name": "base",
"state": "live",
"metadata": { "user": "u1" },
"timeout": 300,
"started_at": "2024-01-15T10:30:00Z"
},
{
"sandbox_id": "sbx-e5f6g7h8",
"template_id": "tpl-base",
"name": "base",
"state": "paused",
"metadata": { "user": "u1" },
"timeout": 300,
"started_at": "2024-01-15T09:00:00Z"
}
],
"total": 7,
"next_token": "MToxNzA1MzA5MjAwMDAwMDAwOnNieC1lNWY2ZzdoOA"
}
Error Responses
| Status | Cause |
|---|---|
400 | An unknown state, or a metadata filter or next_token that can’t be read |
401 | Missing or invalid API key |
500 | Internal error listing sandboxes |