Create & manage rentals

This page covers the full lifecycle. All endpoints need a key with the rental scope (except GET /balance, which any active key can call).

Create a rental

POST /rentals starts a GPU. It returns immediately with status: "pending" — the GPU is still provisioning, so there's no connection URL yet. Poll GET /rentals/{id} for that.

curl -X POST https://paraloncloud.com/api/v1/rentals \
  -H "Authorization: Bearer prlc_your_key_here" \
  -H "Idempotency-Key: my-run-001" \
  -H "Content-Type: application/json" \
  -d '{"node_id": "<from /gpus>", "type": "jupyter"}'

Body

Field	Required	Meaning
node_id	yes	The node to rent, from GET /gpus. Must be a valid node UUID.
type	no	"jupyter" (default) — a full JupyterLab environment. It's the only supported type.
hours	no	Whole hours (1–720). Sets an auto-stop: the rental stops itself after this long. Omit for an open-ended rental that runs until you stop it.
name	no	A label for your own reference.

Idempotency

Send an Idempotency-Key header on create. If the request is retried with the same key, you get back the same rental instead of accidentally starting (and paying for) a second GPU.

Response

{
  "rental_id": "276bffe6-8ade-4ca2-82af-f31f7a5e76c7",
  "status": "pending",
  "node_id": "a13ee904-...",
  "type": "jupyter",
  "price_per_hour": 0.12,
  "expires_at": "2026-07-13T00:10:53Z",
  "message": "Rental is provisioning. Poll GET /rentals/{rental_id} until connection_pending is false for connection details."
}

Open-ended vs time-limited

• Open-ended (no hours): runs until you DELETE it. Bills per minute the whole time.
• Time-limited (hours: N): auto-stops after N hours. expires_at is set, and a server-side reaper stops it at that time using the same path as a manual destroy. Great for jobs that shouldn't outlive their budget if your script crashes.

Get connection details (poll)

GET /rentals/{id} returns the current status and, once running, the connection details.

curl https://paraloncloud.com/api/v1/rentals/<rental_id> \
  -H "Authorization: Bearer prlc_your_key_here"

{
  "rental_id": "276bffe6-...",
  "status": "running",
  "connection": {
    "access_url": "https://<subdomain>.trycloudflare.com?token=<token>",
    "tunnel_url": "https://<subdomain>.trycloudflare.com",
    "jupyter_token": "<token>"
  },
  "price_per_hour": 0.12,
  "expires_at": "2026-07-13T00:10:53Z"
}

Poll every few seconds until connection_pending is false — the connection URL comes up a few seconds after status becomes "running", so running with an empty connection is normal, not a failure. A rental you don't own returns 404 — the same as one that doesn't exist.

List your rentals

GET /rentals returns your active rentals by default (what's running and billing). Pass ?status=all for the full history including stopped ones.

curl https://paraloncloud.com/api/v1/rentals \
  -H "Authorization: Bearer prlc_your_key_here"

Check your balance

GET /balance — rentals draw from your credit balance.

curl https://paraloncloud.com/api/v1/balance \
  -H "Authorization: Bearer prlc_your_key_here"

{ "balance": 9.49, "earnings_balance": 0.10, "currency": "USD" }

Destroy a rental

DELETE /rentals/{id} stops the GPU and stops billing. This is your money brake — it's safe to call twice (an already-stopped rental returns success, not an error).

curl -X DELETE https://paraloncloud.com/api/v1/rentals/<rental_id> \
  -H "Authorization: Bearer prlc_your_key_here"

Errors

Status	Error	When
401	invalid_api_key	Missing or wrong key
403	insufficient_scope	Key lacks the rental scope
402	insufficient_credits	Balance won't cover the rental
404	rental_not_found / node_not_found	Unknown id, or not yours
409	node_rented / node_offline / node_not_ready / rental_limit_reached	Node unavailable, or your key hit max_active_rentals
429	rate_limit_exceeded	Too many requests (creates are limited more strictly)

Billing is per minute while a rental is running. Always DELETE rentals you're done with — or set hours so they auto-stop even if your process dies.