Skip to main content
GET
/
api
/
containers
List Containers
curl --request GET \
  --url https://api.example.com/api/containers \
  --header 'Authorization: <authorization>'
{
  "containers": [
    {
      "id": "<string>",
      "db_id": "<string>",
      "user_id": "<string>",
      "name": "<string>",
      "image": "<string>",
      "role": "<string>",
      "status": "<string>",
      "created_at": "<string>",
      "last_used_at": "<string>",
      "idle_seconds": 123,
      "mfa_locked": true,
      "resources": {
        "resources.memory_mb": 123,
        "resources.cpu_shares": 123,
        "resources.disk_mb": 123
      },
      "ip_address": "<string>"
    }
  ],
  "count": 123,
  "limit": 123
}

​
Endpoint

GET /api/containers
Returns a list of all containers (including stopped and creating containers) for the authenticated user. The response includes real-time status synchronized with Docker, resource allocation, and usage statistics.

​
Request Headers

​
Authorization
string
required
Bearer token for authentication
Bearer YOUR_API_TOKEN

​
Response

​
containers
array
Array of container objects
​
count
integer
Total number of containers
​
limit
integer
Maximum containers allowed for your tier

​
Status Codes

  • 200 OK - Containers retrieved successfully
  • 401 Unauthorized - Missing or invalid API token
  • 500 Internal Server Error - Server-side error

​
Examples

curl -X GET https://your-rexec-instance.com/api/containers \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Response Example

{
  "containers": [
    {
      "id": "a3b5c7d9e1f2",
      "db_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "usr_123abc",
      "name": "dev-environment",
      "image": "ubuntu:24.04",
      "role": "node",
      "status": "running",
      "created_at": "2024-01-15T10:30:00Z",
      "last_used_at": "2024-01-15T14:22:15Z",
      "idle_seconds": 127.5,
      "mfa_locked": false,
      "ip_address": "172.17.0.5",
      "resources": {
        "memory_mb": 2048,
        "cpu_shares": 2000,
        "disk_mb": 10240
      }
    },
    {
      "id": "b8d2a4f6c9e1",
      "db_id": "660f9511-f30c-52e5-b827-557766551111",
      "user_id": "usr_123abc",
      "name": "python-project",
      "image": "ubuntu:24.04",
      "role": "python",
      "status": "stopped",
      "created_at": "2024-01-14T08:15:00Z",
      "last_used_at": "2024-01-14T18:45:00Z",
      "idle_seconds": 0,
      "mfa_locked": false,
      "resources": {
        "memory_mb": 4096,
        "cpu_shares": 4000,
        "disk_mb": 20480
      }
    },
    {
      "id": "770a0622-g41d-63f6-c938-668877662222",
      "db_id": "770a0622-g41d-63f6-c938-668877662222",
      "user_id": "usr_123abc",
      "name": "swift-bear-342",
      "image": "debian:bookworm",
      "role": "",
      "status": "creating",
      "created_at": "2024-01-15T14:25:00Z",
      "last_used_at": "2024-01-15T14:25:00Z",
      "idle_seconds": 0,
      "mfa_locked": false,
      "resources": {
        "memory_mb": 2048,
        "cpu_shares": 2000,
        "disk_mb": 10240
      }
    }
  ],
  "count": 3,
  "limit": 5
}

​
Container Status

The status field indicates the current state:
  • creating - Container is being initialized (pulling image, setting up environment)
  • configuring - Container is running but still installing development tools
  • running - Container is fully ready and accepting connections
  • stopped - Container is stopped but data is preserved
  • error - Container creation or operation failed

​
Filtering and Pagination

The List endpoint returns all containers for the authenticated user. Containers are sorted by creation date (newest first). For large datasets, consider implementing client-side filtering and pagination.

​
Usage Statistics

​
Idle Time

The idle_seconds field shows how long a container has been inactive. This is useful for:
  • Identifying containers to stop to save resources
  • Implementing auto-stop policies
  • Monitoring usage patterns
// Find containers idle for more than 1 hour
const idleContainers = containers.filter(c => 
  c.status === 'running' && c.idle_seconds > 3600
);

​
Resource Utilization

// Calculate total resource usage
const totalMemory = containers.reduce((sum, c) => 
  sum + c.resources.memory_mb, 0
);
const totalCPU = containers.reduce((sum, c) => 
  sum + c.resources.cpu_shares, 0
);

console.log(`Total: ${totalMemory}MB RAM, ${totalCPU/1000} CPU cores`);

​
Including Agents

If you have connected BYOS (Bring Your Own Server) agents, they appear in the containers list with an agent: prefix in the ID. Agents show status as online or offline.

​
Notes

Real-time Sync: Container statuses are synchronized with Docker on each request. For stopped containers, the database status is returned. This ensures accurate state information but may add slight latency to the response.
Monitoring: For real-time container updates (status changes, creation progress), connect to the WebSocket events endpoint instead of polling this endpoint.

​
See Also

​
Get Container

GET /api/containers/:id
Retrieve details for a specific container by ID.

​
Path Parameters

​
id
string
required
Container ID (Docker ID or database ID)

​
Response

Returns a single container object with the same structure as the list endpoint.

​
Example

curl -X GET https://your-rexec-instance.com/api/containers/a3b5c7d9e1f2 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Status Codes

  • 200 OK - Container found
  • 401 Unauthorized - Missing or invalid API token
  • 404 Not Found - Container does not exist or you don’t have access

Build docs developers (and LLMs) love

Get started for freeTalk to us