> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ornn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rent GPUs by the hour: Spot and On-demand

Open **Buy Now**. **Pay as you go** is selected by default. The `/payg` route rents GPUs by the hour, a node at a time. You choose how many nodes, **Spot** or **On-demand**, and a location or any location. Each node you get gives you every GPU free on it; the VMs run until something ends them, and you prepay each hour as you go.

Pay-as-you-go capacity is the idle time on capacity that other customers and suppliers relisted or listed. Every signed-in organization can use it; you do not need reservation approval.

## Spot or On-demand

* **Spot** VMs are interruptible: a reservation that starts on the node ends the VM.
* **On-demand** VMs are never interrupted by reservations. They run until you stop them, the seller stops them, or the listing ends. Only nodes with no reservation before the listing ends offer On-demand, so it can be scarcer or cost more.

A node can offer both. GPUs bought either way are taken from both.

## Choose a location

Every listing sells at a location, such as **US East 11**. **Any location** buys the best price anywhere; choosing a location buys only there. Locations are the same for every seller, so one location combines all capacity in that area.

## Buy at the market price

Choose a **GPU type**, a **location** (or **Any location**), **Spot** or **On-demand**, and the number of nodes. Each node gives you every GPU free on it, which can be fewer than the node has when someone else is using part of it. Only combinations with capacity on offer are selectable.

Your order takes the lowest available asking prices, oldest first at each price, until it has every node; capacity belonging to your organization is skipped. Nodes can come from different listings and cost different amounts. The hourly price is the total of each node's matched rate times the GPUs you get on it, including Ornn's fees. No fee is added on top.

**1. Choose your capacity**

Select a GPU type and use the stepper to choose how many nodes. The form shows how many nodes have GPUs free now and caps the stepper there. Availability updates automatically and is checked again before submission.

**2. Choose a VM boot disk**

Every VM boots the disk you choose. **Quick Start** lists ready-made Ornn disks; **Your disks** lists the disks your organization created or uploaded on [Disks](/guides/vm-access.md#disks). Disk choices show their base image and its OS logo in its brand color when identified. Unrecognized or missing OS metadata uses a generic disk icon. If **Your disks** is empty, click **Create a disk** to open the creation modal without leaving the form. Your new disk is selected when you finish. The form starts on your organization's newest disk, or the newest Ornn disk if your organization has none. A disk that has not been built yet is built when the VMs first launch, which can take up to several minutes; a note under the disk choices says so before you buy.

**3. Review the price**

The form shows the total hourly rate and **First charge** for the first hour. The first-hour charge is rounded. There is no fixed lifetime total; each later hour is prepaid separately.

**Estimated time until interrupted** shows when the VMs are scheduled to end, or **no scheduled end**. For Spot, a future reservation or removal of the listing can interrupt a VM sooner; for On-demand, only removal of the listing can. If one node is interrupted, only its VM stops.

**4. Review payment and buy**

Click **Buy now** to open payment details. Your Ornn credits are used first, then your saved card. Add a card inline if your credits do not cover the first hour, or use **Change** to replace a saved card. The summary shows your machine image, estimated hourly charge, credits applied, and the remaining amount billed in the first hour. Click **Checkout** to submit.

Checkout stays disabled while availability or payment details cannot be confirmed. If the price increases or capacity changes before submission, review the updated order before continuing. If nodes sell to someone else while you check out, you get the ones still free and are not charged for the rest.

Checkout stays open until the console confirms that your VMs are ready, then opens the reservation's detail page directly, or **Nodes** when the nodes came from several listings, without a success modal or timed redirect. If no node was bought, the console shows an error. If payment fails, a **Payment failed** modal offers **Update payment method** or **Cancel**, keeping your GPU type, node count and machine-image selections. Updating your card does not automatically place another order.

If your order ends for another reason, checkout reports that it ended and directs you to **Nodes** for its final status.

If confirmation is still pending, an inline alert keeps that status visible. Use **Check status** to check again without placing another bid. A slow response is not treated as a payment failure; the console blocks another purchase until the existing order is confirmed or ends. Check **Nodes** if you are unsure whether the VMs were created.

In **Nodes**, follow VM startup progress and manage your spot reservations. To view spot order history or cancel a resting bid, use the [Spot API or CLI](#use-the-api). Nothing is charged for nodes a bid has not bought.

## Your spot VMs

The nodes one listing sells you are one spot reservation in **Nodes**, listed with your other reservations; a purchase across several listings makes one reservation for each. Its reservation detail page shows each VM's startup progress until it is ready. Manage it there like any VM: SSH keys, connection details, and the disk it boots.

Each spot VM is an isolated VM with its GPUs and their share of the node's CPUs, memory, and disk. A node you get runs one VM with all of your GPUs on it, except on hosts whose GPUs can only be split in powers of two: there 6 GPUs run as a 4-GPU and a 2-GPU VM. Disk capacity is based on the filesystem used to store VM disks, which may be separate from the host OS disk. Each VM starts from the disk chosen at purchase. A created disk that has not been built yet is built on that first launch, which takes longer.

## Paying for spot hours

Each hour is prepaid when it starts. Billing uses the hourly rate agreed for your
reservation; later changes to the listing's advertised price do not change that rate.
Reservation details and usage reports use that agreed rate too. Listing changes
also leave existing reservations' agreed terms unchanged.

1. Ornn credits pay first.
2. Your saved card pays whatever credits do not cover.

The card has a $0.50 minimum charge. If the part left for the card would be less than $0.50, Ornn charges \$0.50 and keeps the difference as Ornn credits for later hours.

When a spot reservation ends partway through an hour, Ornn credits the unused part of that hour back to your Ornn credits. Startup time is not billed. If its VMs fail to start, or are not ready before the first prepaid hour ends, the reservation stops and the unused prepayment returns as Ornn credits.

## How spot ends

A running spot reservation has no end date. Once it stops, its end date records when it ended.

A spot reservation runs until one of these happens:

* **You stop it.** Click **Stop VM** on the reservation in **Nodes**. Its VMs shut down and its GPUs go back on the book.
* **You cancel during startup.** The cancellation remains in effect while setup finishes. Any resulting VMs are stopped, and the GPUs return to the book after cleanup.
* **The seller ends it.** The seller can withdraw the listing, but not while your VM runs with a [preemption notice](#preemption-notice); they take its node back instead.
* **The seller takes the node back.** The seller can preempt the node your VM runs on. The node stops selling at once, and your VM keeps running until its preemption notice has passed, then it stops.
* **A reservation needs its GPUs (Spot only).** Reserved windows always take priority over Spot. When a buyer's reserved window starts and needs GPUs your Spot VMs are using, the Spot reservation ends. On-demand VMs are never ended this way.
* **The listed capacity ends.**
* **The VMs cannot start.** If provisioning fails or the VMs are not ready before the first prepaid hour ends, the run ends and unused prepayment returns as Ornn credits.
* **An hour cannot be paid.** If your card is declined for any hour, including the first, the spot run ends: its VMs are stopped and the GPUs return to the book. Update your card in **Billing** before you buy again.

Save your work outside the VM. A Spot VM can end with little notice when a reservation starts on its node. The estimated time until interrupted counts only reservations already sold and the end of the listed capacity. A reservation bought later or the seller can end a Spot VM sooner; only the seller can end an On-demand VM sooner.

### Preemption notice

Each Spot and On-demand VM carries the preemption notice of the capacity it was bought on, fixed at purchase. Relisted capacity always gives one hour. The reservation's `preemptNoticeSeconds` shows it. When the seller takes the node back, your VM gets at least that much warning before it stops, and the stopped reservation's `endReason` is `listing_ended`.

When the seller takes the node back, Ornn also tries to warn you right away. Delivery is not guaranteed, so plan around the notice itself:

* Every member of your organization gets an email with the time the VM stops.
* The VM's serial console shows a line starting with `[ORNN-PREEMPT]`, for example:

  ```text theme={null}
  [ORNN-PREEMPT] This VM will be stopped at 2026-10-21T05:00:00Z.
  ```

To react from inside the VM, watch for that line or the files Ornn writes beside it:

* **Serial console log.** Open the reservation in **Nodes** and select the **Serial console** log.
* **System journal.** Run `journalctl -t ornn -f`.
* **Logged-in terminals.** The line is broadcast to open SSH sessions.
* **Machine-readable file.** `/run/ornn/preemption.json` holds the stop time:

  ```json theme={null}
  {
    "kind": "preemption",
    "noticeId": "…",
    "stopAt": "2026-10-21T05:00:00Z",
    "message": "[ORNN-PREEMPT] This VM will be stopped at 2026-10-21T05:00:00Z."
  }
  ```

A VM whose guest agent is stopped still gets the serial console line, written from its host. The journal, terminal broadcast, and file need the guest agent, so keep `qemu-guest-agent` running in custom disks.

## Use the API

You can bid with an [API key](/api-keys.md), the [Ornn CLI](/cli.md), or the [MCP server](/mcp-server.md) instead of the console. Every member of your organization can bid; approval is not required. Prices are integer micro-USD per GPU-hour: `2500000` is \$2.50. They are the same prices the Pay as you go page shows, and a bid's price is the most you pay per GPU-hour. The [order book API reference](/api-reference/order-books/list-books.md) lists every field and error.

The API cannot save a card. A bid is not refused when no card is saved, but an unpaid first hour blocks VM startup. Save a card in **Billing** before bidding unless your Ornn credits cover the hours. [Check for a saved card](/api-reference/billing/payment-method.md) through the API: the response is `{"saved": true}` when one is saved.

### 1. Read the book and quote a bid

```bash CLI theme={null}
ornn market books --sale-type spot
ornn market book --gpu-slug nvidia_h100_sxm --region us-east-11
ornn market quote --gpu-slug nvidia_h100_sxm --nodes 2
```

```bash REST theme={null}
export ORNN_API_URL="https://api.ornn.com"

curl --fail-with-body "$ORNN_API_URL/v1/markets/books?saleType=spot" \
  -H "Authorization: Bearer $ORNN_API_KEY"

curl --fail-with-body \
  "$ORNN_API_URL/v1/markets/books/nvidia_h100_sxm/quote?nodes=2&orderType=market&saleType=spot" \
  -H "Authorization: Bearer $ORNN_API_KEY"
```

```python Python theme={null}
import os
import requests

API = "https://api.ornn.com"
http = requests.Session()
http.headers["Authorization"] = f"Bearer {os.environ['ORNN_API_KEY']}"

books = http.get(f"{API}/v1/markets/books", timeout=30)
books.raise_for_status()
print(books.json()["orderBooks"])

quote = http.get(f"{API}/v1/markets/books/nvidia_h100_sxm/quote",
                 params={"nodes": 2, "orderType": "market"},
                 timeout=30)
quote.raise_for_status()
for node in quote.json()["nodes"]:
    print(node["pricePerGpuHourMicroUsd"], node["gpus"], node["interruptsAt"])
```

Each book has a `gpuSlug` (the GPU type), a `saleType` (`spot` or `on-demand`) and a `region`: a location slug such as `us-east-11`, or `any` for the book of bids that take any location. Location display names come from `GET /v1/orchestrator/locality/regions` (`facility_slug` and `facility_name`). Each ask level of the book counts the GPUs free at that price and the nodes they are on; bid levels count the GPUs bids still want. Book, trade and quote reads take `saleType` (default `spot`) and an optional `region`; without one they span every location. The quote takes `gpus` or `nodes`, like a bid (`nodes` with `orderType=market`), and places nothing. It returns one entry per node a bid would take now, in order, with the price you would pay per GPU-hour, the `gpus` it would take on that node, the `region` it would run in and `interruptsAt`, the next scheduled end on that node: a sold reservation (`reservation`, Spot only) or the end of the listed capacity (`listing_end`). Less than you asked for means the rest would wait (limit) or be cancelled (market).

### 2. Place a bid

A bid asks for exactly one of `gpus` or `nodes`, one or more. With `gpus` it takes GPUs until it has enough, so one node can supply part of a bid and a bid can span nodes. With `nodes` it takes that many nodes with a GPU free, and every GPU free on each; the console's node stepper, the CLI and the MCP server send `nodes`. `nodes` needs a `market` bid: a limit bid takes `gpus`, and a limit bid for `nodes` is refused with `nodes_need_market_order`. Sending both is refused with `quantity_conflict`, and neither or a value below one with `invalid_quantity`. `saleType` is `spot` (the default) or `on-demand`; `region` limits the bid to one location and is otherwise any location. An unknown region is refused with `unknown_region`. `diskId` chooses the disk every VM boots. A `limit` bid takes capacity at or below your price, cheapest first, and waits on the book for the rest. Trades execute at the resting order's price: a new bid pays the existing asks; new capacity crossing your waiting bid fills at your bid price. For example, a $2/GPU-hour ask crossing an existing $2.50/GPU-hour bid executes at \$2.50/GPU-hour, including fees. That matched rate is saved on your reservation. A `market` bid takes what is for sale now and cancels the rest.

Every bid needs an `Idempotency-Key` header. Use a new key for each bid and keep it: if the response is lost, send the same request with the same key to get the original order back instead of placing a second bid. The CLI generates a key for you unless you pass `--idempotency-key`.

```bash CLI theme={null}
ornn market bid --gpu-slug nvidia_h100_sxm --nodes 2 --sale-type on-demand --region us-east-11 \
  --idempotency-key <key> --yes --format json
```

```bash REST theme={null}
export BID_KEY="$(uuidgen)"

curl --fail-with-body -X POST "$ORNN_API_URL/v1/markets/orders" \
  -H "Authorization: Bearer $ORNN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BID_KEY" \
  --data '{"gpuSlug": "nvidia_h100_sxm", "saleType": "on-demand", "region": "us-east-11", "nodes": 2, "orderType": "market"}'
```

```python Python theme={null}
import uuid

bid_key = str(uuid.uuid4())  # reuse only to retry this exact bid
response = http.post(
    f"{API}/v1/markets/orders",
    headers={"Idempotency-Key": bid_key},
    json={"gpuSlug": "nvidia_h100_sxm", "nodes": 2, "orderType": "market"},
    timeout=30,
)
response.raise_for_status()
order = response.json()["order"]
print(order["orderId"], order["status"], order["fillIds"])
```

A new bid returns HTTP `201`; a retry with the same key returns `200` and the original order. The order reports its `saleType`, its `region` (null for any location), `requested` and `remaining` in GPUs (a bid for nodes records the GPUs it took), `filledNodes` and `filledGpus`, and `fillIds`: each fill is the GPUs the bid bought from one listing, and its ID is also its spot reservation ID. Check `order.status`:

* `filled`: the bid bought everything it asked for.
* `resting`: a limit bid is waiting on the book for the rest; its fills so far are running.
* `cancelled`: the rest of the bid was withdrawn. A market bid cancels whatever was not for sale (`cancelReason: unfilled_market_order`); what it bought keeps running, and nothing is charged for the rest.

### 3. Follow the fills

Poll [Get an order](/api-reference/order-books/get-order.md), [List your orders](/api-reference/order-books/list-orders.md) or [List your fills](/api-reference/order-books/list-fills.md) as a resting bid fills. A fill is a trade record and never changes. Read each fill's reservation with [Get a reservation](/api-reference/reservations/get.md), using the fill ID. The reservation can take a moment to appear. While it runs, its `endsAt` is null. A fill does not mean the VMs are ready: follow startup and connect as described in [VM access](/guides/vm-access.md).

### 4. Cancel a bid or stop VMs

Cancelling a bid stops it buying more. Ending a fill stops its reservation and its VMs.

```bash CLI theme={null}
ornn market cancel --order-id <order-id> --yes
ornn market end --fill-id <fill-id> --yes
```

```bash REST theme={null}
curl --fail-with-body -X DELETE "$ORNN_API_URL/v1/markets/orders/<order-id>" \
  -H "Authorization: Bearer $ORNN_API_KEY"

curl --fail-with-body -X POST "$ORNN_API_URL/commerce/reservations/<fill-id>/stop" \
  -H "Authorization: Bearer $ORNN_API_KEY"
```

```python Python theme={null}
response = http.delete(f"{API}/v1/markets/orders/{order['orderId']}", timeout=30)
response.raise_for_status()
print(response.json()["order"]["status"])

for fill_id in order["fillIds"]:
    response = http.post(f"{API}/commerce/reservations/{fill_id}/stop", timeout=30)
    response.raise_for_status()
    print(response.json()["endsAt"], response.json()["pendingOperation"])
```

Cancelling a resting bid returns `status: cancelled`; its fills keep running. A fill's ID is its reservation's ID, so ending a fill is [stopping its reservation](/api-reference/virtual-machines/stop.md): its VMs stop and its GPUs go back on the book, and the reservation's `endReason` is `stop`. When a reservation ends for another reason, `endReason` says why: `preempted_by_reservation`, `listing_ended`, `payment_failed`, or `provisioning_failed`.

Stopping also works while the VMs are still provisioning. A `202` response with `pendingOperation: stop` acknowledges the request; read the reservation until `endsAt` is set.

## What's next

> **[Relist capacity](/guides/resale.md)**
>
> Sell time on your reservation at your own asking price.

> **[Billing and payment](/guides/usage-and-billing.md)**
>
> Save a card and see how spot hours and reservations are billed.

To add a saved card during checkout, enter the card number, expiry, and CVC in the card field, then select **Save card** beside it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.