Rental lifecycle

A rental moves through five statuses. Getting the transitions right is most of what a correct integration does.

                  ┌──────────────┐
  POST /rentals → │ provisioning │
                  └──────┬───────┘
                    ┌────┴─────┐
                    ▼          ▼
              ┌─────────┐  ┌────────┐
              │ running │  │ failed │  ← never became usable
              └────┬────┘  └────────┘
                   │ stop, preemption, spend limit
                   ▼
              ┌──────────┐
              │ stopping │  ← still billing, still holds a slot
              └────┬─────┘
                   ▼
              ┌─────────┐
              │ stopped │  ← accrued_cents is final
              └─────────┘

Status	Usable?	Billing	`access`
`provisioning`	No	Hold placed, nothing accrued	`null`
`running`	Yes	Accruing per second	Populated
`stopping`	No	Final charge not settled	May still be present
`stopped`	No	`accrued_cents` is final	`null`
`failed`	Never was	Nothing charged	`null`

provisioning and running and stopping are all live: each occupies a slot under the concurrency ceiling.

Polling

rental = create_rental(...)

while rental["status"] == "provisioning":
    time.sleep(3)
    rental = get_rental(rental["id"])

if rental["status"] == "failed":
    handle_failure(rental["failure_code"])
else:
    connect(rental["access"])

Loop while the status is provisioning, not while it is not running. The second version spins forever on a failed rental — the most common bug in a first integration, and one that only shows up on a bad day.

Poll every two to three seconds. Provisioning takes tens of seconds; polling five times a second spends your whole rate limit to learn the same thing.

Two traps worth stating plainly

`201 Created` does not mean ready

POST /rentals returns immediately with provisioning. The machine does not exist yet, access is null, and nothing is reachable. Everything after the create call has to wait for running.

`stopping` does not mean stopped

POST /rentals/{id}/stop returns stopping. Teardown is asynchronous and the final charge is computed when the machine is actually gone.Two consequences:

billing.accrued_cents is not final until the status is stopped.
The rental still occupies a concurrency slot. Stop one and immediately start its replacement, and you can hit max_active_rentals_reached with what feels like a single machine.

Poll until stopped before doing either.

Why it ended

Once a rental leaves running, termination_reason says why:

Value	Meaning
`stopped_by_user`	You, or someone on your account, stopped it
`preempted`	A spot rental was reclaimed — see Spot
`stopped_by_operator`	We stopped it; support will have the reason
`spend_limit_reached`	The daily spend cap on the creating key was crossed
`failed`	It ended without ever running
`null`	Still live

When it never came up

status: "failed" means the machine never became usable. Nothing is charged for a failed rental. failure_code says what to do next:

provisioning_failed

The machine was allocated but never came up. Retry, or pick another offer — retrying the same offer is reasonable once, since this is often a single bad host.

capacity_unavailable

The capacity disappeared during start-up. Retry with backoff; prefer a different offer if it happens twice.

internal_error

Our fault. Quote the rental id to support.

We do not publish the upstream’s error text. It names infrastructure this API deliberately keeps out of view, and its wording changes without notice — so a handler written against it would break silently. The three codes above are stable and are what you should branch on.

The event history

Rather than diffing polled objects to work out what happened, read the history:

curl -s https://api.gpuoutlet.ai/v1/rentals/rnt_8h2k4m/events \
  -H "Authorization: Bearer $GPUOUTLET_API_KEY"

{
  "data": [
    { "id": "evt_1", "type": "rental.created",  "created_at": "2026-07-29T14:02:11.000Z", "data": { } },
    { "id": "evt_2", "type": "rental.running",  "created_at": "2026-07-29T14:02:47.000Z", "data": { } },
    { "id": "evt_3", "type": "rental.stopping", "created_at": "2026-07-29T17:31:02.000Z", "data": { } },
    { "id": "evt_4", "type": "rental.stopped",  "created_at": "2026-07-29T17:31:40.000Z", "data": { } }
  ],
  "meta": { "next_cursor": null }
}

Append-only, oldest first, cursor-paginated. Events are pruned after 90 days.

Event	When
`rental.created`	The rental was accepted
`rental.running`	It became usable
`rental.stopping`	Teardown was requested
`rental.stopped`	It is gone; billing is final
`rental.preempted`	A spot rental was reclaimed
`rental.failed`	It never became usable

data holds the rental as it looked when the event was recorded. History is not rewritten by today’s serializer, so an old event may lack fields added since — read it defensively.

These are the same event names webhook deliveries will carry. A handler written against this list keeps working when webhooks ship, so it is worth shaping your code around events now rather than around polled diffs.

Get started

API keys

Conventions

Catalog

Rentals

Radar

Polling

Two traps worth stating plainly

Why it ended

When it never came up

The event history

​Polling

​Two traps worth stating plainly

​Why it ended

​When it never came up

​The event history

Polling

Two traps worth stating plainly

Why it ended

When it never came up

The event history