Skip to main content
Set or extend the auto-shutdown timeout for a sandbox. When the timeout expires, the sandbox will be automatically deleted.

​
Endpoint

PUT /v1/sandboxes/:id/timeout

​
Request

​
Headers

Authorization: Bearer $HOPX_API_KEY
Content-Type: application/json

​
Path Parameters

ParameterTypeDescription
idstringSandbox ID

​
Body Parameters

ParameterTypeRequiredDescription
timeout_secondsintegerYesNew timeout duration in seconds from now

​
Example Request

Set timeout to 1 hour (3600 seconds): 
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 3600
  }'
Extend timeout by 2 hours: 
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 7200
  }'

​
Response

​
Success (200 OK)

{
  "id": "sandbox_abc123xyz",
  "timeout_seconds": 3600,
  "expires_at": "2025-01-28T01:00:00Z",
  "request_id": "req_abc123"
}

​
Response Fields

FieldTypeDescription
idstringSandbox ID
timeout_secondsintegerNew timeout duration in seconds
expires_atstringISO 8601 timestamp when sandbox will expire
request_idstringRequest ID for debugging

​
Status Codes

CodeDescription
200Timeout updated successfully
400Invalid timeout value
401Authentication required
404Sandbox not found

​
Errors

​
Invalid Timeout (400)

{
  "error": "Invalid timeout value: must be positive",
  "code": "INVALID_REQUEST",
  "request_id": "req_abc123"
}
Cause: The timeout_seconds value is negative, zero, or invalid. Fix: Ensure timeout_seconds is a positive integer.

​
Sandbox Not Found (404)

{
  "error": "Sandbox not found",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req_abc123"
}
Cause: The sandbox ID doesn’t exist or belongs to another organization. Fix: Verify the sandbox ID is correct.

​
Important Notes

  • Absolute timeout - The timeout is set from the current time, not relative to the previous timeout
  • Auto-deletion - When the timeout expires, the sandbox is automatically deleted
  • Can be extended - You can extend the timeout multiple times
  • No maximum - There’s no maximum timeout limit (subject to your plan)

​
Use Cases

​
Extend Timeout for Long-Running Task

# Check current expiration
curl https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq '.expires_at'

# Extend by 2 hours
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 7200
  }'

​
Set Timeout on Creation

# Create sandbox with 1 hour timeout
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 3600
  }'

​
Keep Sandbox Alive Indefinitely

# Set a very long timeout (e.g., 30 days)
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 2592000
  }'

​
Next Steps