Sandboxes ›

Set sandbox auto stop

PUT/v1/sandboxes/{id}/auto-stop

Moves the stop of the run under way, later or sooner: to a time, or a number of seconds from now. It holds until the sandbox stops, and its next start runs for ttlSeconds again. Moved again, the last move counts, and a PATCH that changes ttlSeconds puts it back to the last start and ttlSeconds. It is at least 60 seconds from now, and at most maxTtlSeconds of GET /v1/policy from now: a sandbox runs on for as long as something keeps moving its stop. Every move is the event sandbox.auto_stop_set, which says who moved it.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
await sandbox.setAutoStop({ inSeconds: 3600 });

Answer200 OK · SandboxAutoStop

{
"sandboxId": string,
"status": "creating" | "running" | "stopped" | "error" | "deleted" | "restoring" | …,
"autoStopAt": string | null,
"secondsLeft": integer | null,
"ttlSeconds": integer | null,
"setBy": "ttl" | "account" | "sandbox" | "null" | null,
}

When it is to be stopped now.

Path

idrequired

string

e.g. "sbx_0123456789abcdef"

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Body

`at` string	When to stop it. e.g. `"2026-10-20T18:00:00Z"`
`inSeconds` integer	How many seconds from now to stop it. e.g. `7200`

Returns

200 When it is to be stopped now.

SandboxAutoStop6 fields

sandboxId

string

status

creatingrunningstoppederrordeletedrestoringmigrating

autoStopAt

stringnull

When the sandbox is to be stopped.

Null when it is not running, or has no time limit.

secondsLeft

integernull

Seconds from now until then.

Null with autoStopAt.

ttlSeconds

integernull

Seconds each start runs before it is stopped, unless the stop is moved.

Null is the deployment's default.

setBy

ttlaccountsandboxnullnull

What decided autoStopAt.

ttl: its last start and ttlSeconds. account: a PUT of this with one of its account's API keys, or the console. sandbox: a PUT of this by the sandbox itself. Null with autoStopAt.

Errors and other answers

400	`auto_stop_too_soon` it is less than 60 seconds from now.
400	`auto_stop_too_far` it is more than maxTtlSeconds from now. The stop is left as it was.
404	Not found.
409	`invalid_state` the sandbox is not running, or it reached its stop and is being stopped now. ttlSeconds says how long its next start runs.
409	`no_time_limit` the sandbox's own token asked, and the sandbox has no time limit: only its account gives it one.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Get sandbox auto stop Clear sandbox auto stop →