What this covers
The lifecycle endpoints describe what an instance was provisioned as. These describe what it is doing — current CPU, GPU, RAM and network use, pod health, recent events, container logs, and one-shot command execution. All of them need instances:read unless noted, and only ever reach instances owned by the same account.
Read one instance
A single instance, serialized exactly like an entry from GET /api/instances.
Live resource usage
Allocation, live usage, and burn rate in one response — a utilization number is not actionable without the ceiling it is measured against. Percentages are computed against the instance's own allocation, not the host machine.
curl -H "Authorization: Bearer $GPUTW_API_KEY" https://gputw.ai/api/instances/<instance-id>/resourcesEach metric is a number or null — never a substituted zero. The source field reports where the sample came from: prometheus (live scrape), fallback (secondary poller), or none (no telemetry). That way an idle instance at 0% is distinguishable from one that is not reporting. GPU fields are null on machines without GPU telemetry.
Poll status while deploying
A small, cheap response meant to be polled in a loop while waiting for a box to come up. It carries the platform status, the deploy sub-phase (SCHEDULING, PREPARING, PULLING_IMAGE, STARTING, CONFIG_ERROR, START_FAILED, CRASH_LOOP, RUNNING), the container's own phase and readiness, restart count, and a failure reason when there is one.
curl -H "Authorization: Bearer $GPUTW_API_KEY" https://gputw.ai/api/instances/<instance-id>/statusPrefer this over polling the full instance list. Large image pulls take minutes, and deployPhase tells you whether the box is still being prepared, already starting, or stuck in a way worth acting on. PREPARING covers everything kubelet reports as ContainerCreating — sandbox setup, storage attach and the image pull are not distinguishable from outside the node — so it is not a promise that a pull is running.
Everything running right now
Every DEPLOYING and RUNNING instance paired with its live pod state and current utilization, in one call.
Events and logs
Events arrive as structured records rather than text. Logs accept ?tail= (up to 2000 lines) and ?previous=1, which reads the container that ran before the current one — on a crash loop that is the only place the real error appears.
curl -H "Authorization: Bearer $GPUTW_API_KEY" "https://gputw.ai/api/instances/<instance-id>/logs?tail=100&previous=1"Infrastructure identifiers are removed from events, logs, and command output before they leave the server: worker hostnames and private IP addresses are replaced with placeholders.
Billing history for one instance
The billing sessions this instance has been through, newest first, each with its start and end, the hardware and hourly rate in force, and the duration. These are the records the ledger is built from.
Run a command
Runs one command in the container and returns stdout, stderr, and exitCode. command is an array of arguments, passed through with no shell in between — so nothing is re-split or glob-expanded. For pipes or globs, ask for a shell yourself: ["sh","-c","..."].
curl -X POST https://gputw.ai/api/instances/<instance-id>/exec \
-H "Authorization: Bearer $GPUTW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":["nvidia-smi","--query-gpu=utilization.gpu","--format=csv"]}'This is a root shell on your instance, and needs the separate instances:exec scope — no preset except full includes it. Every call is written to your audit trail with the command and exit code (never the output). The instance must be RUNNING; output is capped at 256 KB per stream and the command at 30 seconds by default (timeoutMs, max 120 seconds).
Restart the container
Recreates the container in place, keeping the image, ports, and workspace. Needs instances:manage.
Custom-image instances cannot restart this way — their registry credentials are cleared when the instance stops or fails, so a redeploy has to name a template or supply the image again.
Shut down from inside the instance
The one instance endpoint that takes no API key. It authenticates with GPUTW_CONTROL_TOKEN, an instance-scoped token injected into every container alongside GPUTW_API_URL. The token proves only which instance is calling, so it cannot reach any other instance or any other part of your account — which is what makes it safe to leave inside a container your own code runs in. GPUtw base images wrap this as gputw-shutdown; call it directly from a custom image that is not built on one.
curl -X POST "$GPUTW_API_URL/api/instances/self-stop" \
-H "Authorization: Bearer $GPUTW_CONTROL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"stop"}'action is stop (the default — the instance record and /vault survive) or terminate (delete the instance).
The reply is 202 Accepted and the shutdown happens after it is sent. That ordering is deliberate: stopping deletes the very pod the request came from, so answering first is what keeps the caller from reporting a failure for a shutdown that actually succeeded. Sending stop to an already-stopped instance succeeds and changes nothing.
Use the public $GPUTW_API_URL exactly as injected. Tenant containers are blocked from private-network egress, so a private address for the API will not resolve to anything reachable.