List Sandboxes

Discover how to retrieve sandbox environments and navigate large result sets using pagination controls.

Using the TypeScript SDK

List all sandboxes in your account:

example.ts

import SandboxSDK from '@avmcodes/sandbox-sdk';

const client = new SandboxSDK({
  apiKey: process.env['SANDBOX_SDK_API_KEY'],
});

// List all sandboxes (first page)
const response = await client.sandboxes.list();

console.log(`Found ${response.pagination.total_items} sandboxes`);
response.data.forEach(sandbox => {
  console.log(`${sandbox.name} (${sandbox.id}) - Status: ${sandbox.status}`);
});

Basic Listing

Get the first page of sandboxes with default pagination:

basic-listing.ts

const response = await client.sandboxes.list();

// Access the sandboxes array
const sandboxes = response.data;

// Access pagination metadata
const { page, page_size, total_pages, total_items } = response.pagination;

console.log(`Page ${page} of ${total_pages}`);
console.log(`Showing ${sandboxes.length} of ${total_items} sandboxes`);

Custom Pagination

Specify page number and page size:

custom-pagination.ts

// Get the second page with 10 items per page
const response = await client.sandboxes.list({
  page: 2,
  page_size: 10,
});

response.data.forEach(sandbox => {
  console.log(`- ${sandbox.name} (${sandbox.status})`);
});

Iterating Through All Pages

Fetch all sandboxes by iterating through pages:

iterate-pages.ts

async function getAllSandboxes() {
  const allSandboxes = [];
  let currentPage = 1;
  let hasMorePages = true;

  while (hasMorePages) {
    const response = await client.sandboxes.list({
      page: currentPage,
      page_size: 20,
    });

    allSandboxes.push(...response.data);

    hasMorePages = currentPage < response.pagination.total_pages;
    currentPage++;
  }

  return allSandboxes;
}

const allSandboxes = await getAllSandboxes();
console.log(`Total sandboxes: ${allSandboxes.length}`);

Filtering by Status

Filter sandboxes by their status:

filter-status.ts

const response = await client.sandboxes.list();

// Filter running sandboxes
const runningSandboxes = response.data.filter(
  sandbox => sandbox.status === 'running'
);

console.log(`Running sandboxes: ${runningSandboxes.length}`);

// Filter by other statuses
const creatingSandboxes = response.data.filter(
  sandbox => sandbox.status === 'creating'
);

Accessing Sandbox Details

Each sandbox object contains detailed information:

sandbox-details.ts

const response = await client.sandboxes.list();

response.data.forEach(sandbox => {
  console.log('Sandbox Details:');
  console.log(`  ID: ${sandbox.id}`);
  console.log(`  Name: ${sandbox.name}`);
  console.log(`  Status: ${sandbox.status}`);
  console.log(`  CPUs: ${sandbox.cpu}`);
  console.log(`  Memory: ${sandbox.memory} MB`);
  console.log(`  Created: ${sandbox.created_at}`);

  if (sandbox.volumes && sandbox.volumes.length > 0) {
    console.log(`  Volumes: ${sandbox.volumes.length}`);
    sandbox.volumes.forEach(volume => {
      console.log(`    - ${volume.volume_name} mounted at ${volume.mount_path}`);
    });
  }
});

Counting Sandboxes

Get a quick count of your sandboxes:

count-sandboxes.ts

const response = await client.sandboxes.list({
  page: 1,
  page_size: 1, // Minimal data transfer
});

console.log(`Total sandboxes: ${response.pagination.total_items}`);
console.log(`Total pages: ${response.pagination.total_pages}`);

Response Structure

The list() method returns a SandboxListResponse object:

response-structure.ts

const response = await client.sandboxes.list();

// Response structure:
// {
//   data: Sandbox[],
//   pagination: {
//     page: number,
//     page_size: number,
//     total_pages: number,
//     total_items: number
//   }
// }

Example Response

example-response.ts

const response = await client.sandboxes.list();

// response.data contains an array of sandboxes:
response.data.forEach(sandbox => {
  console.log(sandbox.id);        // "sbx_x1y2z3a4b5c6d7e8"
  console.log(sandbox.name);      // "My Sandbox"
  console.log(sandbox.status);    // "running"
  console.log(sandbox.cpu);       // 2
  console.log(sandbox.memory);    // 512
  console.log(sandbox.created_at); // "2024-01-15T12:00:00Z"
  console.log(sandbox.volumes);   // Array of mounted volumes
});

// response.pagination contains pagination metadata:
console.log(response.pagination.page);        // 1
console.log(response.pagination.page_size);   // 20
console.log(response.pagination.total_pages);  // 5
console.log(response.pagination.total_items); // 100

Sandbox Status

Sandboxes can have various statuses:

• creating — Sandbox is being created

• running — Sandbox is active and ready

• stopped — Sandbox has been stopped

• deleting — Sandbox is being deleted

Parameters

page number default:"1"

Page number to retrieve (starts at 1)

page_size number default:"28"

Number of items per page (1-100)

Response Fields

Data Array

Each item in the data array is a Sandbox object.

Pagination Object

The pagination object contains page, page_size, total_pages, and total_items.

Examples

Find a Specific Sandbox by Name

find-by-name.ts

async function findSandboxByName(name: string) {
  let currentPage = 1;
  let hasMorePages = true;

  while (hasMorePages) {
    const response = await client.sandboxes.list({
      page: currentPage,
      page_size: 20,
    });

    const found = response.data.find(sandbox => sandbox.name === name);
    if (found) {
      return found;
    }

    hasMorePages = currentPage < response.pagination.total_pages;
    currentPage++;
  }

  return null;
}

const sandbox = await findSandboxByName('My Sandbox');
if (sandbox) {
  console.log('Found:', sandbox.id);
}

Get All Running Sandboxes

get-running.ts

async function getAllRunningSandboxes() {
  const runningSandboxes = [];
  let currentPage = 1;
  let hasMorePages = true;

  while (hasMorePages) {
    const response = await client.sandboxes.list({
      page: currentPage,
      page_size: 20,
    });

    runningSandboxes.push(
      ...response.data.filter(s => s.status === 'running')
    );

    hasMorePages = currentPage < response.pagination.total_pages;
    currentPage++;
  }

  return runningSandboxes;
}

const running = await getAllRunningSandboxes();
console.log(`Found ${running.length} running sandboxes`);

Monitor Sandbox Count

monitor-count.ts

async function monitorSandboxCount() {
  const response = await client.sandboxes.list({ page: 1, page_size: 1 });

  return {
    total: response.pagination.total_items,
    running: response.data.filter(s => s.status === 'running').length,
    creating: response.data.filter(s => s.status === 'creating').length,
  };
}

const stats = await monitorSandboxCount();
console.log('Sandbox Statistics:', stats);

Best Practices

1

Use appropriate page sizes

Choose a page_size that balances between too many requests and too much data per request.

2

Cache pagination metadata

Cache total_items and total_pages to plan pagination without extra requests.

3

Handle empty results

Always check if the data array is empty before processing.

4

Respect rate limits

When iterating through pages, consider adding delays between requests if needed.

5

Filter client-side

Use client-side filtering for status or other properties rather than making multiple API calls.