GPU rental reference
A rental is two objects:
- A workload describes what to run: the image, the hardware, SSH keys, ports and disk. You can reuse it.
- A deployment is one running instance of a workload. It is billed per started minute while it is
ready. Pulling the image and starting up are free, and so is a deployment that fails.
All endpoints live under https://api.green-compute.com and take Authorization: Bearer <key>, except where marked public.
Hardware
| GPU id | VRAM | Price per GPU-hour | Available |
|---|---|---|---|
rtx4090 | 24 GB | $0.40 | yes |
rtx5090 | 32 GB | $0.70 | yes: use a CUDA 12.8+ image (see below) |
These are the current figures. The authoritative live source is GET /platform/pricing (public): it is what billing actually uses, and each GPU there carries availability, worked out by the scheduler from what is free this instant (net of everything already placed or reserved): available, almost_fully_rented, fully_rented or on_request (see Pricing). available_now is true exactly while some are free. We don't publish how many GPUs are free or how many we have. The rentals page shows the same state.
GET /platform/nodes/supported (public) is the list of GPU ids that have a machine online. A GPU we price but have no machine for is left out (its availability is on_request), and asking for it fails with a 400. A GPU that is listed but fully_rented is merely full: asking for it fails with a 503 no_capacity and a Retry-After, and nothing is created. GPU ids are matched without regard to case or separators, so rtx4090, RTX 4090 and rtx-4090 are the same.
A multi-GPU rental needs its GPUs free on one machine, so a GPU that is available does not guarantee room for a 4-GPU rental. If there isn't room, the create fails at once with 503 no_capacity, whose message says so, and nothing is created: join the waitlist for that many GPUs together, or write to support@green-compute.com for more capacity. Two requests racing for the last GPU can both pass the check; the loser is then retried by the scheduler for about two minutes and, if nothing frees up, fails with a last_error that says to join the waitlist or write to us.
RTX 5090 needs a CUDA 12.8+ image. The 5090 is Blackwell (
sm_120). Images built for older CUDA, such aspytorch/pytorch:2.2.0-cuda12.1-*, start fine but fail the moment you use the GPU.pytorch/pytorch:2.7.0-cuda12.8-cudnn9-runtimeworks on both cards.
Create a workload — POST /platform/workloads
{
"name": "my-gpu-box",
"kind": "pod",
"image": "pytorch/pytorch:2.7.0-cuda12.8-cudnn9-runtime",
"requirements": {
"gpu_count": 1,
"supported_gpu_models": ["rtx4090"],
"min_vram_gb_per_gpu": 24,
"cpu_cores": 8,
"memory_gb": 32
},
"metadata": {
"ssh_public_keys": ["ssh-ed25519 AAAA... you@laptop"],
"requested_ports": [8888],
"volume_size_gb": 50,
"command": "python train.py --epochs 3",
"env": { "HF_HOME": "/workspace/hf" },
"secret_env": { "WANDB_API_KEY": "wandb" }
}
}
| Field | Meaning |
|---|---|
kind | Must be "pod" for a rental. Always send it: when it is missing, the workload is created as a model deployment ("inference"). |
image | Any public Docker image. SSH is injected at start-up, so the image does not need its own SSH server. |
requirements.gpu_count | 1 to 8 GPUs, all on one machine. More than the largest machine has (8) is refused at once with 422 validation_error; detail[0].ctx.le is the limit. |
requirements.supported_gpu_models | GPU ids you accept. Leave it empty to accept any; the quoted rate is then the highest. |
requirements.cpu_cores, memory_gb | Capped at the machine's fair share for the number of GPUs you take. |
metadata.ssh_public_keys | Your public keys. They are authorised for root. Recommended: no private key ever has to leave your machine. New to SSH keys? See Create an SSH key. |
metadata.requested_ports | Up to 10 container ports to expose (for example Jupyter on 8888). Their public host ports appear in the deployment's port_mappings. |
metadata.volume_size_gb | Disk for /workspace, 10 to 2000 GB. Default 50. |
metadata.command | Optional. A shell command (or a list of arguments) to run when the pod starts, so a job needs no SSH session. It runs in the background from /workspace once SSH is up, with its output appended to /workspace/greencompute-command.log. The pod keeps running after the command finishes, so set max_runtime_minutes on the deployment, or DELETE it when you're done, to stop paying. Up to 8192 characters. |
metadata.restart_policy | Optional. What happens when metadata.command exits: never (the default) leaves it stopped, on-failure runs it again if it exited with an error, always runs it again whenever it exits. Best run your job in the foreground. If the command starts it with & and returns, use always: the command is run again once everything it started has ended, and nothing it started is ever killed, so two copies never run side by side. Jobs moved away with screen, tmux or setsid can't be followed, so don't combine those with a restart policy. The wait between runs starts at 5 seconds and doubles up to 5 minutes while runs keep ending within a minute. While /workspace/greencompute-command.pause exists the command isn't started or restarted, also after the pod is suspended and resumed; delete the file to start it. Each exit (with its exit code) and restart is written to /workspace/greencompute-command.log, which is cut once it passes 50 MB, keeping the previous part in greencompute-command.log.1. If the container itself stops (out of memory, say), it is restarted and the command starts again, whatever the policy. |
metadata.env | Optional. Environment variables for the pod, as {"NAME": "value"}, up to 64 (together with secret_env). They are set for the start command and for SSH sessions. Values never appear in API responses, but they are stored with the workload: put tokens and passwords in secret_env instead. |
metadata.secret_env | Optional. Environment variables filled from your saved secrets, as {"NAME": "<secret name>"}. Only the names are stored with the workload; the values are handed to the machine when the pod starts, and no response ever contains them. An unknown name is refused with 422 (detail names the variable). A variable can't be in both env and secret_env. |
The response contains workload_id.
Other workload fields in the API schema (runtime, lifecycle, tags, security_tier, pricing_class) are for model deployments and have no effect on a pod. In particular, lifecycle.shutdown_after_seconds does not stop a pod; use max_runtime_minutes on the deployment instead.
Secrets
Keep tokens, passwords and keys as account secrets rather than in a workload. A secret's value can be written but never read back: no request returns it (not the secrets list, nor workloads, deployments, events, logs or MCP). It is handed only to the machine starting a rental that uses it.
curl -s -X POST https://api.green-compute.com/platform/secrets \
-H "Authorization: Bearer $GC_KEY" -H "Content-Type: application/json" \
-d '{"name": "wandb", "value": "…"}'
# {"secret_id": "…", "name": "wandb", "public_key": null, "created_at": "…", "updated_at": "…"}
Then name it in a pod's metadata.secret_env, e.g. {"WANDB_API_KEY": "wandb"}: the pod gets WANDB_API_KEY set to the value. A model you deploy takes "hf_token_secret": "<secret name>" for its Hugging Face token instead of hf_token.
| Call | Does |
|---|---|
POST /platform/secrets | Saves {"name", "value"} (name up to 128 characters, value up to 4096). Names are unique on your account: a name you already use returns 409 conflict with that secret's detail.secret_id. |
GET /platform/secrets | Your secrets' names and dates, never their values. |
PUT /platform/secrets/{id} | Replaces the value: {"value": "…"}. Workloads naming it keep working; rentals started from then on get the new value, running ones keep theirs. |
DELETE /platform/secrets/{id} | Deletes it. Running rentals keep the value they started with; a new deployment of a workload that names it is refused with 422. |
A workload that uses secrets can be started only by the account that owns it (and whose secrets they are), even if it is shared. A key with the read scope can list names; creating, replacing and deleting secrets needs rentals (or a full-access key). Anyone who can SSH into a rental, or run commands in it, can read its environment, so a key that can start rentals with your secrets can see them that way.
Secrets named ssh-key:<label> are the website's saved SSH keys (Rentals > SSH keys): their value must be an SSH public key, which isn't secret, so it comes back as public_key (and as value, for older clients). For every other secret public_key is null and there is no value.
Start it — POST /platform/deployments
{ "workload_id": "…", "max_runtime_minutes": 120 }
| Field | Meaning |
|---|---|
workload_id | The workload to run. |
save_on_exhaustion | Optional. true keeps the pod and its disk if your balance runs out (or a spend limit pauses it), at $1 per day for up to 30 days, so you can resume it; see Running out of balance. Default false: the pod and its disk are deleted 15 minutes after it stops. |
resume_on_topup | Optional, default false. With save_on_exhaustion, a pod paused for an empty balance is resumed by itself, within a minute of a top-up that covers an hour of everything you would then have running. You get an email when it comes back. Change it later with PATCH /platform/deployments/{id} {"resume_on_topup": true}. |
max_runtime_minutes | Optional. Stops the deployment automatically this many minutes after it became ready, so a crashed or forgotten client can't keep paying. 1 to 43200 (30 days). No limit when omitted. |
name | Optional. Your name for this rental, e.g. rig-07: letters, digits, ., _ and -, up to 48, starting with a letter or digit. The pod sees it as GC_DEPLOYMENT_NAME (and its id as GC_DEPLOYMENT_ID), so a start command can use it as a pool's worker name. Without one, GC_DEPLOYMENT_NAME is the first 8 characters of the id. Use a different name per rental if a pool should tell them apart. Rename with PATCH /platform/deployments/{id} {"name": "…"} ("" removes it): the API shows the new name at once, and the pod gets it the next time it starts (a resume, or a move to another machine); a pod that is running keeps the name it started with. |
The response is the deployment. Fields worth reading:
| Field | Meaning |
|---|---|
deployment_id | Use this for every later call. |
state | See the lifecycle below. |
hourly_rate_cents | Price per GPU-hour, in cents. At creation it is the most this deployment can cost; once a GPU is assigned, it becomes that card's exact rate, which is never higher. |
deployment_fee_usd | Always 0. There is no deployment fee. |
port_mappings | {container_port: public_host_port} once running. |
ready_at | When it first became ready, which is when billing started. |
max_runtime_minutes | The automatic stop you asked for, if any. |
last_error | Set if placement or start-up failed, or why it stopped. |
Starting requires at least one hour of the quoted rate times gpu_count in your balance. Otherwise you get 402 (see Errors).
Retrying a create safely
If a create times out, you can't tell whether it went through. Send an Idempotency-Key header (any unique string up to 255 characters, such as a UUID) on POST /platform/workloads and POST /platform/deployments. Resending the same request with the same key within 24 hours returns the first result, with the response header Idempotent-Replayed: true, instead of renting a second machine. A request that failed (for example with 402) isn't remembered, so you can fix the problem and retry with the same key. Reusing a key with a different body returns 422; a retry that arrives while the first attempt is still running returns 409 with Retry-After.
Lifecycle
pending → scheduled → pulling → starting → ready
│
suspended ◄── (balance ran out)
│
terminated ◄── DELETE, or max_runtime_minutes reached
failed means it could not be placed or started. Read last_error. Poll GET /platform/deployments/{id} every 5–10 seconds; most rentals are ready within one to three minutes.
Fleets
POST /platform/fleets keeps a number of rentals of one workload going, so you don't need a watchdog of your own:
{ "workload_id": "…", "target": 8, "replace": true, "name_prefix": "rig" }
| Field | What it does |
|---|---|
target | How many rentals, 1 to 64. Each is an ordinary deployment, billed as usual. |
replace | true (default): keep target running. Any that stops or fails is replaced, under the same name. false: start target as GPUs free up, then stop; members that end aren't replaced. |
name_prefix | Members are named rig-01, rig-02, …, which the pod sees as GC_DEPLOYMENT_NAME. A replacement takes the name of the one it replaces. Default: from the workload's name. |
max_runtime_minutes, save_on_exhaustion, resume_on_topup | Applied to every member, as on a deployment. |
The fleet checks every 30 seconds. When it can't start one, it waits and says why in status: no GPU free, not enough credit (it starts only as many as your balance covers an hour of, counting what is already running), or the API key's or account's limits. It never replaces a member that is paused because the balance ran out. A member paused at a spend limit isn't replaced either: a keep-N-running fleet resumes it, oldest first, once the limit has room for an hour of it, and says how many are waiting in status. If its machine is gone, the fleet replaces it; if its machine is only full, a saved member is kept (never deleted for that) and an unsaved one is replaced after about 2 minutes without room. If three in a row fail before they are ready (a broken image, say), the fleet pauses with the reason; fix the workload, then resume it. It also pauses, saying which, when its workload names a secret you have since deleted: create it again, then resume.
| Call | What it does |
|---|---|
GET /platform/fleets, GET /platform/fleets/{id} | The fleet: running/target, state (active, paused, completed), status in plain English, and its members. |
PATCH /platform/fleets/{id} {"target": 12} | More starts more; fewer stops the extras, not-yet-ready ones first, then the highest numbers. |
PATCH /platform/fleets/{id} {"paused": true} / false | Pause or resume starting and replacing. Members keep running while paused. |
DELETE /platform/fleets/{id} | Stop the fleet and its rentals, and delete the fleet; ?keep_running=true stops and deletes only the fleet, and its rentals carry on as ordinary rentals. The answer is the fleet as it stopped (state: "stopped", deleted_at); after that it is no longer listed, and GET, PATCH or DELETE of it return 404. To stop it starting and replacing members but keep it, PATCH {"paused": true} instead. |
Creating a fleet accepts an Idempotency-Key header, like creating a deployment. On the website, set How many rentals and Keep this many running on the rental form; fleets show at the top of My Rentals.
Running out of balance
When your balance reaches zero, a running pod is suspended: the container stops and its GPU is released, and GPU billing stops. What happens next depends on save_on_exhaustion:
save_on_exhaustion | After suspension |
|---|---|
true | The disk is kept for up to 30 days, billed at $1 per day. Storage keeps being charged even though the balance is empty, so the balance can go negative. Top up and POST /platform/deployments/{id}/resume to restart the pod with its disk intact; resuming needs one hour of balance. After 30 days the pod and its disk are deleted. |
false (default) | The pod and its disk are deleted 15 minutes after suspension. |
While a pod is suspended, its deployment shows storage_cents_per_day (what keeping it costs, 0 if it isn't saved) and deletes_at (when it and its disk will be deleted unless you resume it). Suspended pods are also listed under Paused rentals on the My Rentals page, with Resume and Delete buttons.
Resuming by itself. A saved pod created with resume_on_topup: true (or ticked "Resume it automatically when I add credit" on My Rentals) is resumed for you within a minute of a top-up, once your balance covers an hour of everything that would then be running, oldest pause first, and you are emailed what came back; it also waits until any spend limit has room for an hour of it. A pod paused by hand, or a private model paused for being idle, is never resumed this way.
Paused at a spend limit. A spend limit you set (for the account or an API key) pauses running pods the same way, with suspended_reason: "spend_limit": the disk is kept on the same terms as above. A keep-N-running fleet brings its members back by itself, and so does a pod with resume_on_topup, once the limit has room for an hour of them; otherwise resume it once spending is back under the limit. See Paused at a spend limit.
Before it runs out. GET /platform/billing/forecast says what everything running costs per hour and how long your balance lasts at that rate; you are emailed once when that drops under 24 hours and once more under 2 hours. See Adding credit.
DELETE /platform/deployments/{id} deletes the pod and its disk at any time, including a suspended one, and its storage charge stops. Copy anything you need off /workspace first.
Connect — GET /platform/deployments/{id}/ssh
{
"ssh_host": "…",
"ssh_port": 40123,
"ssh_username": "root",
"ssh_command": "ssh root@… -p 40123",
"private_key": "-----BEGIN OPENSSH PRIVATE KEY-----…",
"host_keys": [
{"type": "ssh-ed25519", "key": "ssh-ed25519 AAAAC3…", "fingerprint": "SHA256:A2j3vFHU…"}
],
"known_hosts": ["[…]:40123 ssh-ed25519 AAAAC3…"]
}
A pod becomes ready only once its SSH server is accepting connections, so you can connect the moment you see that state; until then /ssh answers 404. If SSH can't be brought up in your image at all (no apt-get, apk, yum or dnf, or the container exits on start), the deployment fails instead, unbilled, with the reason in last_error.
If you supplied ssh_public_keys, only your keys can log in and private_key is null. If you didn't, the platform generates a key for the pod and private_key holds it: it is returned only by this endpoint, every retrieval is audit-logged, and it never appears in create, get, list or delete responses.
Check the host key
Host ports are reused from one rental to the next, so a port you have used before can now lead to a new pod with a different host key, and ssh then warns REMOTE HOST IDENTIFICATION HAS CHANGED. Rather than turning host-key checking off, check against the keys we publish. host_keys are the pod's own keys, read from the pod once its SSH server is up, and known_hosts has them as ready-made lines for this host and port. Keep one file per rental:
curl -s "$GC_API/platform/deployments/$DEPLOYMENT_ID/ssh" -H "Authorization: Bearer $GC_KEY" \
| jq -r '.known_hosts[]' > ~/.ssh/gc-$DEPLOYMENT_ID.known_hosts
ssh -o UserKnownHostsFile=~/.ssh/gc-$DEPLOYMENT_ID.known_hosts -o StrictHostKeyChecking=yes root@HOST -p PORT
Connecting by hand, compare the fingerprint ssh prints the first time with the one under Host key on the rental's page, or in host_keys. The keys are also on GET /platform/deployments/{id} as ssh_host_keys. Pods started before 30 October 2026 have none listed.
Inside the pod:
- the image's environment is preserved, so
python,condaandCUDA_HOMEbehave as the image defines them, including for one-off commands likessh … python train.py; /workspaceis your persistent disk;nvidia-smishows only the GPUs you rented.
Terminal in the browser
No SSH key? On My Rentals, or on a rental's page, Open terminal opens a shell in your running pod, in the browser. It is the same access SSH gives you, and nothing more: you are root in your own pod, in /workspace, with the image's environment (python, conda, CUDA_HOME as the image defines them). It uses bash when the image has it, otherwise sh. On a phone, a bar above the keyboard adds Esc, Tab, Ctrl and the arrow keys, but a physical keyboard works best.
- Each terminal is a new shell. Reconnecting opens another one; it doesn't pick up the old one.
- Closing the terminal ends its shell and whatever runs in its foreground, as closing an SSH session does. Start long jobs with
nohup,tmuxorscreen, or give the rental a start command (metadata.command), so they keep running. - Up to 3 terminals at once per account (and a few per machine). A terminal closes after 15 minutes with no typing and no output, and after 4 hours in any case; open a new one to carry on.
- Only for pods that are
ready, not for models. Opening one needs therentalsscope, like SSH access.
Open a terminal over the API
For agents and scripts that want an interactive shell (for one command at a time, exec is simpler). A WebSocket can't carry an API key from a browser, so it takes two steps:
-
POST /platform/deployments/{id}/terminalwith your API key, body{}or{"shell": "bash"}(auto, the default, picksbashif installed, elsesh;shforces it). It returns a one-time ticket, valid for 60 seconds, for this rental, your account and this API key:{ "ticket": "k3J…", "expires_in_seconds": 60, "expires_at": "2026-11-16T12:01:00Z", "websocket_url": "wss://api.green-compute.com/platform/deployments/<id>/terminal?ticket=k3J…", "idle_timeout_seconds": 900, "max_session_seconds": 14400 } -
Open the WebSocket at
websocket_urlwithin the minute, adding&cols=120&rows=40for the terminal's size. The ticket works once: every connection needs a new one. Send noOriginheader (browsers on green-compute.com send theirs; other sites' pages are refused).
Messages. Binary frames carry the terminal's bytes, both ways: what you type, and what the shell prints (UTF-8, possibly split mid-character). Text frames are JSON:
| Direction | Message | Meaning |
|---|---|---|
| you → us | {"type": "resize", "cols": 120, "rows": 40} | The terminal's size changed (cols 2–500, rows 2–200). |
| you → us | {"type": "input", "data": "ls -la\n"} | Text to type, if sending binary is awkward. |
| you → us | {"type": "ping"} | Keepalive; answered with {"type": "pong"}. It doesn't count as activity for the idle limit. |
| us → you | {"type": "ready", "idle_timeout_seconds": 900, "max_session_seconds": 14400, "session_ends_at": "…"} | The shell has started; send input from now on. |
| us → you | {"type": "notice", "code": "idle_warning", "message": "…", "seconds_left": 60} | The terminal is about to close (idle_warning, or session_ending before the 4-hour limit). |
| us → you | {"type": "notice", "code": "input_dropped", "message": "…"} | The program in the pod isn't reading input and over 1 MiB is waiting, so the message you just sent was dropped, all of it (never part of one). Nothing else is dropped once the program reads again. |
| us → you | {"type": "exit", "code": 0} | The shell ended (exit, or it was stopped); the connection then closes with code 1000. |
| us → you | {"type": "error", "code": "terminal_idle", "message": "…"} | Why the connection is about to close. |
Close codes. An error closes the connection with code 4000 + its HTTP status, right after an error message saying why (Errors lists the codes):
| Close code | error.code | What to do |
|---|---|---|
1000 | The shell ended normally. | |
4401 | terminal_ticket_invalid | The ticket was unknown, already used, expired, or for another rental or key. Get a new one. |
4403 | forbidden, wallet_blocked | This key or account can't open a terminal here. |
4404 | not_found | No such rental on your account. |
4408 | terminal_idle | 15 minutes with no input and no output. Open a new one. |
4409 | conflict | The rental isn't running, or it is a model, not a pod. |
4410 | terminal_session_limit | The 4-hour limit. Open a new one. |
4429 | terminal_limit | 3 terminals are open on your account (or the machine has its maximum): close one, then retry. |
4501 | not_implemented | The terminal is turned off for now. Use SSH or exec. |
4503 | unavailable | The machine running the rental didn't answer, or the connection to it was lost. Retry in a minute. |
1009 | A message over 1 MiB. Send large input in parts. |
An open terminal is checked again every minute: deleting the API key it was opened with, a blocked account, or the rental stopping closes it (4403, 4409).
Python, with the websockets library:
import asyncio, json, os, sys
import requests, websockets
API, KEY, DEP = "https://api.green-compute.com", os.environ["GC_KEY"], os.environ["DEPLOYMENT_ID"]
async def main():
t = requests.post(f"{API}/platform/deployments/{DEP}/terminal", json={},
headers={"Authorization": f"Bearer {KEY}"}).json()
# Sending the key here too is optional; if you do, it must be the key the ticket was made with.
async with websockets.connect(t["websocket_url"] + "&cols=120&rows=40",
additional_headers={"Authorization": f"Bearer {KEY}"}) as ws:
try:
async for msg in ws:
if isinstance(msg, bytes):
sys.stdout.write(msg.decode(errors="replace"))
continue
m = json.loads(msg)
if m["type"] == "ready":
await ws.send(json.dumps({"type": "input", "data": "nvidia-smi; exit\n"}))
elif m["type"] in ("exit", "error"):
print("\n", m)
except websockets.ConnectionClosedError as e:
print("closed:", e.rcvd.code if e.rcvd else None)
asyncio.run(main())
JavaScript (a browser, or Node 22+):
const API = "https://api.green-compute.com";
const res = await fetch(`${API}/platform/deployments/${id}/terminal`, {
method: "POST",
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
body: "{}",
});
const { ticket } = await res.json();
const ws = new WebSocket(`${API.replace("https", "wss")}/platform/deployments/${id}/terminal` +
`?ticket=${encodeURIComponent(ticket)}&cols=120&rows=40`);
ws.binaryType = "arraybuffer";
const decoder = new TextDecoder(); // output can split a character across frames: decode as a stream
ws.onmessage = (e) => {
if (typeof e.data !== "string") return console.log(decoder.decode(e.data, { stream: true })); // terminal output
const m = JSON.parse(e.data);
if (m.type === "ready") ws.send(new TextEncoder().encode("ls /workspace\n"));
if (m.type === "error") console.error(m.code, m.message);
};
ws.onclose = (e) => console.log("closed", e.code);
When GPUs are rented out
While every GPU of a model is rented, its availability in /platform/pricing is fully_rented, and a create with no room returns 503 with error.code: "no_capacity"; nothing is created. Rentals end and GPUs free up, so rather than retrying, either:
- Join the waitlist.
POST /platform/capacity-alertswith{"gpu_model": "rtx4090", "gpu_count": 1, "count": 2}waits for room forcountrentals ofgpu_countGPUs each (that many free on one machine). When there is, you get one email and acapacity.availableevent (and webhook), and the alert is done. Alerts expire after 7 days; up to 5 can wait at once.GET /platform/capacity-alertslists them andDELETE /platform/capacity-alerts/{id}cancels one. On the website, a rented-out GPU has a Join the waitlist button that sets the same alert. - Rent them as they free up. A fleet with
"replace": falsestarts rentals as GPUs become free and stops at its target.
For more GPUs than are free, or a whole machine, write to support@green-compute.com.
Other calls
| Call | Does |
|---|---|
GET /platform/deployments | Lists your deployments, including stopped ones. Filter with ?state=ready, or several states such as ?state=terminated,failed. Add ?limit=100 to get them a page at a time, newest first: see Paging the list. |
GET /platform/deployments/{id} | One deployment. |
DELETE /platform/deployments/{id} | Stops it, stops billing and deletes its disk. Returns the deployment with state: "terminated". |
POST /platform/deployments/{id}/resume | Restarts a suspended pod in place, with its disk intact. Needs one hour of balance. |
GET /platform/events | Every change on your account since the last call: ready, failed, suspended, terminated. Or have them sent to you as webhooks: see Events and webhooks. |
GET /platform/deployments/{id}/stats | Live readings while it runs: CPU, memory, network, disk, and for each GPU in gpus its use, memory, temperature, power (power_w against power_limit_w), clocks and fan. {} while there are none. |
POST /platform/deployments/{id}/exec | Runs a shell command in a running rental, as root, from /workspace, without SSH: {"command": "./update.sh", "timeout_seconds": 60}. Returns exit_code and the last 64 KiB of output. We wait at most 120 seconds; a longer command keeps running in the pod (timed_out: true), so start long jobs in the background. Needs the rentals scope. On the website, select rentals on My Rentals to run a command on all of them, or stop them all. |
POST /platform/deployments/{id}/terminal | A one-time ticket (60 s) to open an interactive shell in a running rental over a WebSocket: see Terminal in the browser. Needs the rentals scope. |
GET /platform/deployments/{id}/logs?lines=200 | The last lines (up to 2000) of your start command's log and of the container's own output, while it runs. No SSH needed. |
DELETE /platform/workloads/{id} | Deletes the workload definition and the history of its deployments. Your billing history is kept. |
Stopped deployments stay in the list with state: "terminated" until you delete their workload, which removes the workload's deployment history (your billing history is kept).
Paging the list
Without limit or cursor, GET /platform/deployments returns every deployment at once, as it always has. With limit (1 to 500) it returns at most that many, newest first; the state filter applies first. When there are more, the response has two headers:
X-Next-Cursor: MXwyMDI2LTExLTE3VDA5OjE1OjAyLjEyMzQ1NiswMDowMHw4ZjNj…
Link: </platform/deployments?state=ready&limit=100&cursor=MXwyMDI2…>; rel="next"
Request the Link URL (it keeps your state and limit), or send the same state and limit with cursor=<X-Next-Cursor>. The last page has neither header. The cursor is opaque: send it back unchanged; an altered or made-up one returns 400 invalid_cursor. Deployments created while you page sort before the cursor, so a walk sees every older one exactly once; start again without a cursor to see new ones. A cursor without limit gives pages of 100.
import json, urllib.request
API, KEY = "https://api.green-compute.com", "gk_…"
rows, url = [], "/platform/deployments?state=ready,suspended&limit=200"
while url:
req = urllib.request.Request(API + url, headers={"Authorization": f"Bearer {KEY}"})
with urllib.request.urlopen(req) as r:
rows += json.loads(r.read())
cursor = r.headers.get("X-Next-Cursor")
url = f"/platform/deployments?state=ready,suspended&limit=200&cursor={cursor}" if cursor else None
Checking what you've been charged
| Call | Returns |
|---|---|
GET /platform/billing/balance | Your current balance (balance_usd; balance_credits in cents), what you have used but not been charged yet (pending_usage_cents) and the balance less that (available_cents). |
GET /platform/billing/ledger?limit=50&offset=0 | Your billing history, newest first: each entry has kind (usage, topup, …), amount_cents (negative for charges), balance_after, description and created_at. Up to 1000 per page: a larger limit returns 1000, so page on with offset. |
How a rental is billed
Per started minute while running; startup is free. A rental pays for every minute it is ready that it has begun: 10 seconds pays for one minute, 61 seconds for two. Pulling the image, starting up and a deployment that never became ready cost nothing.
- While it runs, usage is metered about once a minute, in proportion to the seconds elapsed, and posted to the ledger in whole cents (
GPU usage 1× GPU @ $0.40/hr), with fractions of a cent carried forward. - When it stops being
ready(you delete it, it fails, it is paused for balance, a spend limit or idleness, it reachesmax_runtime_minutes), the rest of the minute it stopped in and the fraction carried are charged from your balance, rounded up to a cent, in one line ending(final minute). So at $0.40/hr a 10-second rental costs 1¢. If the balance can't cover it (the rental was paused because credit ran out), what it couldn't take is kept as owed and charged when you resume the rental; if you never resume it, that part (at most about a minute) is written off. - Each
readyspell counts on its own: a paused rental that is resumed starts a new one, and the time it was paused is never charged. - While its machine isn't reporting, billing pauses, and that time is never charged.
pending_usage_centsonGET /platform/billing/balance(and/platform/billing/forecast) is what has been used and not charged yet;available_centsis the balance less that.
Limits
| What | Limit per API key |
|---|---|
Every request to /platform/… and /mcp | 20 per second on average, in bursts of up to 40 |
| Workload creates | 30 per minute |
| Deployment creates | 30 per minute |
| Resumes | 30 per minute |
| Chat completions, embeddings | 60 per minute |
| Requests in progress at once to shared models | 8 per account (your own models: no limit) |
| Model listing | 60 per minute |
Terminals: up to 3 open at once per account, each closing after 15 minutes with no input or output and after 4 hours at most; ticket requests count against a per-key rate limit too.
Going over a limit returns 429 rate_limited with a Retry-After header (seconds) and retry_after_seconds in the body (and error). The limits are per API key, never per address.
Every response to a request made with a key says where that key stands against the per-second limit:
| Header | Means |
|---|---|
X-RateLimit-Limit | Requests the key may send at once (the burst, 40). |
X-RateLimit-Remaining | Requests it may send right now. One comes back every 1/20 s. |
X-RateLimit-Reset | Seconds until it is back to the full burst. |
The website and polling every few seconds stay far below it. If you see X-RateLimit-Remaining near 0, slow down, or poll GET /platform/events instead of each rental. Public routes (/platform/pricing, /platform/nodes/supported) and admin keys aren't counted.
Paging parameters are checked: a limit below 1 or a negative offset (or after) is refused with 422 validation_error naming the parameter, rather than answered with a default page.
Limits you set yourself are separate: per API key (max_active_rentals, daily_spend_limit_usd; see limited keys) and for the whole account (GET/PUT /platform/account/limits; see account limits). At one of those, requests return 403 (key_limit, account_spend_limit_reached or account_rental_limit_reached), and at a spend limit running rentals are paused (suspended, kept as when credit runs out) until spending is back under it. Reads such as GET /platform/deployments/{id} count only against the per-second limit; polling every 5–10 seconds is plenty.
One GPU machine per deployment; gpu_count up to the machine size (8): more is a 422 at POST /platform/workloads.
Green Compute