Container Operations & Lifecycle

Manage the runtime state of containers and inspect their transition history. Use these endpoints to start, stop, restart, pause, or resume a container, and to retrieve a paginated audit trail of every status change.

Get container status logs

GET /api/v1/containers/{id}/status-logs

Returns a paginated list of status transition logs for a single container, ordered by transition time by default.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`page`	query	number	No	Page number. Default: `1`
`limit`	query	number	No	Number of results per page. Default: `10`
`sort_by`	query	string	No	Field to sort by. Default: `"transition_time"`. Allowed: `"transition_time"`, `"created_at"`, `"to_status"`, `"from_status"`
`sort_order`	query	string	No	Sort direction. Default: `"desc"`. Allowed: `"asc"`, `"desc"`

Response

{
  "statusCode": 200,
  "message": "Container status logs retrieved successfully",
  "data": {
    "logs": [
      {
        "id": "507f1f77bcf86cd799439077",
        "container_id": "507f1f77bcf86cd799439011",
        "from_status": "stopped",
        "to_status": "running",
        "transition_time": "2025-01-15T10:30:00.000Z",
        "duration_ms": 3500,
        "triggered_by": "user",
        "metadata": {
          "command": "start"
        }
      }
    ],
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 10,
      "totalPages": 2
    }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as `Bearer <token>`
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Error Code	Title	Description	Resolution
`CONTAINER_NOT_FOUND`	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.

SDK usage

const { data } = await client.api.containers.getStatusLogs({
  id: "507f1f77bcf86cd799439011",
  page: 1,
  limit: 10,
  sort_by: "transition_time",
  sort_order: "desc",
});

Manage container

POST /api/v1/containers/{id}/{operation}

Performs a lifecycle operation on a container. The {operation} path segment selects the action.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`operation`	path	string	Yes	Lifecycle operation to perform. Allowed: `"start"`, `"stop"`, `"force-stop"`, `"restart"`, `"pause"`, `"resume"`

This endpoint accepts no request body.

Response

{
  "statusCode": 200,
  "message": "Container operation completed successfully",
  "data": {
    "error": false,
    "operation": "start",
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "message": "Container started successfully",
    "status": "running"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Container is already running",
  "data": {
    "error": true,
    "operation": "start",
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "message": "Container is already running",
    "status": "running"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation	Check the error message for specific field requirements and correct your input
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
`OPERATION_STATE_CONFLICT`	Container State Conflict	The operation cannot be performed because the container is not in the correct state.	Check the container’s current status. For example, a container must be stopped to be started.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as `Bearer <token>`
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status
`OPERATION_NOT_PERMITTED_ON_EXPIRED`	Operation Not Permitted on Expired Container	This operation cannot be performed because the container has expired due to server termination.	The container is in a read-only state. No further operations are allowed. Please create a new container.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Error Code	Title	Description	Resolution
`CONTAINER_NOT_FOUND`	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Error Code	Title	Description	Resolution
`INTERNAL_SERVER_ERROR`	Internal server error	An unexpected error occurred on the server	Try again later, or contact support if the problem persists
`EXTERNAL_SERVICE_ERROR`	External service error	A required external service is unavailable or returned an error	Try again later when the external service is available

SDK usage

const { data } = await client.api.containers.manage({
  operation: "start",
});