> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extend sandbox expiration window

> Extend sandbox expiration window

### Path parameters

<ParamField path="id" type="string (uuid)" required>
  Sandbox identifier
</ParamField>

### Request body

`ExtendSandboxRequest`

<ParamField body="additional_seconds" type="integer" required />

### Response

`SandboxResponse`

<ResponseField name="sandbox_id" type="string (uuid)" required>
  Unique sandbox identifier
</ResponseField>

<ResponseField name="org_id" type="string" required>
  Organization that owns this sandbox
</ResponseField>

<ResponseField name="session_id" type="string" required>
  Session identifier
</ResponseField>

<ResponseField name="status" type="string" required>
  Current sandbox status
</ResponseField>

<ResponseField name="pod_ip" type="string">
  Internal pod IP address
</ResponseField>

<ResponseField name="sandbox_epoch" type="integer" required>
  Sandbox recycle epoch counter
</ResponseField>

<ResponseField name="allocated_vcpu" type="number">
  Allocated vCPU cores
</ResponseField>

<ResponseField name="allocated_memory_gib" type="number">
  Allocated memory in GiB
</ResponseField>

<ResponseField name="created_at" type="string (date-time)" required>
  ISO 8601 creation timestamp
</ResponseField>

<ResponseField name="expires_at" type="string (date-time)" required>
  ISO 8601 expiration timestamp
</ResponseField>

<ResponseField name="max_expires_at" type="string (date-time)" required>
  Maximum possible expiration
</ResponseField>

<ResponseField name="max_lifetime_seconds" type="integer" required>
  Maximum sandbox lifetime in seconds
</ResponseField>

<ResponseField name="remaining_extend_seconds" type="integer" required>
  Seconds available for extension
</ResponseField>

<ResponseField name="lifetime_used_seconds" type="integer" required>
  Seconds of lifetime consumed
</ResponseField>

<ResponseField name="lifetime_used_percent" type="number" required>
  Percentage of lifetime consumed
</ResponseField>

<ResponseField name="startup_metrics" type="object">
  Startup timing breakdown

  <Expandable title="startup_metrics">
    <ResponseField name="total_ms" type="number" required>
      Total startup time in milliseconds
    </ResponseField>

    <ResponseField name="pod_creation_ms" type="number" required>
      Pod creation time
    </ResponseField>

    <ResponseField name="pod_ready_ms" type="number" required>
      Time until pod ready
    </ResponseField>

    <ResponseField name="phases" type="object[]" required>
      <Expandable title="phases">
        <ResponseField name="name" type="string" required />

        <ResponseField name="durationMs" type="number" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning           |
| ----- | ----------------- |
| `200` | Sandbox extended  |
| `404` | Sandbox not found |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.sandbox.stateset.app/api/v1/sandbox/{id}/extend' \
    --header "Authorization: Bearer $STATESET_SANDBOX_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
    "additional_seconds": 250
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "creating",
    "pod_ip": "string",
    "sandbox_epoch": 1,
    "allocated_vcpu": 1.5,
    "allocated_memory_gib": 1.5,
    "created_at": "2026-08-31T14:22:05Z",
    "expires_at": "2026-08-31T14:22:05Z",
    "max_expires_at": "2026-08-31T14:22:05Z",
    "max_lifetime_seconds": 250,
    "remaining_extend_seconds": 250,
    "lifetime_used_seconds": 250,
    "lifetime_used_percent": 7.5,
    "startup_metrics": {
      "total_ms": 250,
      "pod_creation_ms": 250,
      "pod_ready_ms": 250,
      "phases": [
        {
          "name": null,
          "durationMs": null
        }
      ]
    }
  }
  ```
</ResponseExample>