> ## 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. # Place a Spot bid > Bids for one VM with 1, 2, 4, or 8 GPUs on one node. A limit bid fills now against the lowest ask at or below your price, fees included, or rests on the book; a market bid fills now or is cancelled with cancelReason unfilled_market_order. Each bid fills against one ask with room for all its GPUs and never against your own organization's capacity. Some asks sell only to 8-GPU bids, and a 2- or 4-GPU bid also needs a matching group of GPUs free on the node. A filled bid has status running and becomes a spot reservation with the same ID. The reservation appears shortly after the fill; poll GET /commerce/reservations/{reservationId} using the orderId. Each hour is prepaid when it starts, from Ornn credits first and then your saved card. The bid is not refused for a missing card, but if the first or a later hour cannot be paid the reservation ends with endReason payment_failed. Save a card in the console before bidding unless your credits cover the hours. Requires Idempotency-Key. To buy several VMs, place one bid per VM, each with its own key. Available to every member of your organization; approval is not required. CLI equivalent: `ornn spot bid --gpu-slug --gpus 8 --price-per-gpu-hour-micro-usd 2700000 --yes`. Pass `--idempotency-key` to make a retry safe. Send a new `Idempotency-Key` for each bid. If the response is lost, retry with the same key and body: you get the original order back instead of a second bid. See [Rent GPUs on Spot](/guides/spot#use-the-api). ## OpenAPI ````yaml openapi.yaml POST /v1/markets/spot/orders openapi: 3.1.0 info: title: Ornn compute API version: 1.0.0 description: >- Customer HTTP API for Ornn GPU capacity. It covers reserved capacity and nodes, VM and Bare Metal access, Kubernetes and Slurm clusters, SSH keys, storage volumes and GitHub repositories, private networks, monitoring, buying and selling capacity (Reserve, Market, Spot, and Relist), and billing. API keys are scoped to one organization and act with their creator's access there; account, team, and API-key management stay in the console. Most operations require an approved organization. See https://docs.ornn.com/api-keys to create a key and https://docs.ornn.com/guides/kubernetes-api for an end-to-end Kubernetes integration. Examples use fictional IDs and credentials. The info.version field identifies the contract revision, not a shared API path version. contact: email: support@ornn.com servers: - url: https://api.ornn.com description: Production security: - OrnnApiKey: [] tags: - name: Authentication - name: Reservations - name: GPU nodes - name: Clusters - name: Workers - name: Virtual machines description: >- Choose a VM disk, launch VM access on a reservation, and read each VM's status, launch progress, and SSH connection details. - name: Bare Metal description: >- Launch Bare Metal access on a reservation, read a host's readiness and SSH connection details, and reboot or hard reset it. - name: SSH keys description: >- Register public keys for your organization, choose which keys a VM or Bare Metal reservation uses, and queue key delivery to machines. Slurm clusters take organization key IDs at launch. Kubernetes API access does not use SSH keys. - name: Reserve description: >- Browse reserved-capacity listings and their terms, and post, cancel, or accept offers. Reserve listings are visible to approved organizations. - name: Market description: >- Browse relisted capacity and buy windows at the asking price, paid up front. Open to every member of your organization. - name: Spot description: >- Hourly order books for VMs with 1, 2, 4, or 8 GPUs on one node: read books, trades, and quotes, place and cancel bids, and follow fills. - name: Relist description: >- Sell whole nodes from a reservation you hold at your asking price, and manage those listings. - name: Storage description: >- Managed volumes, their files, and GitHub repository pulls. Volumes belong to the API key's creator in the key's organization. - name: Networks description: >- Organization private networks and the WireGuard configs you use to reach private machines and clusters. - name: Monitoring description: >- Machine telemetry and console logs for capacity your organization holds. Reads are limited to your reservation window. - name: Billing description: >- Invoices, billing summary, usage cost, Ornn credits, and account statements. Saving a card and paying invoices stay in the console. externalDocs: description: REST integration walkthrough url: >- https://docs.ornn.com/guides/kubernetes-access#provision-and-manage-through-rest paths: /v1/markets/spot/orders: post: tags: - Spot summary: Place a Spot bid description: >- Bids for one VM with 1, 2, 4, or 8 GPUs on one node. A limit bid fills now against the lowest ask at or below your price, fees included, or rests on the book; a market bid fills now or is cancelled with cancelReason unfilled_market_order. Each bid fills against one ask with room for all its GPUs and never against your own organization's capacity. Some asks sell only to 8-GPU bids, and a 2- or 4-GPU bid also needs a matching group of GPUs free on the node. A filled bid has status running and becomes a spot reservation with the same ID. The reservation appears shortly after the fill; poll GET /commerce/reservations/{reservationId} using the orderId. Each hour is prepaid when it starts, from Ornn credits first and then your saved card. The bid is not refused for a missing card, but if the first or a later hour cannot be paid the reservation ends with endReason payment_failed. Save a card in the console before bidding unless your credits cover the hours. Requires Idempotency-Key. To buy several VMs, place one bid per VM, each with its own key. Available to every member of your organization; approval is not required. operationId: capacityPlaceSpotBid parameters: - name: Idempotency-Key in: header required: true description: >- Required. A unique key of 1 to 200 characters for this operation, such as a UUID. Retrying with the same key and the same body returns the original result with HTTP 200 instead of creating a second one. The key is remembered for 24 hours per organization; reusing it for a different request returns 409 idempotency_conflict. A missing key returns 400 idempotency_key_required. schema: type: string minLength: 1 maxLength: 200 example: 3f1c2a9e-6b1d-4c55-9a77-0d2b8f1e4c10 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CapacitySpotBidRequest' example: gpuSlug: nvidia_h100_sxm gpus: 8 orderType: limit pricePerGpuHourMicroUsd: 2700000 responses: '200': description: >- A retry with the same Idempotency-Key and body; returns the original order's current state. content: application/json: schema: $ref: '#/components/schemas/CapacitySpotOrderEnvelope' example: order: orderId: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa orderBookId: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb gpuSlug: nvidia_h100_sxm side: bid orderType: limit pricePerGpuHourMicroUsd: 2500000 requestedGpus: 8 remainingGpus: 8 status: resting cancelReason: null aggressorSide: null listingId: null nodeId: null createdAt: '2026-10-14T18:30:00.000Z' filledAt: null endedAt: null endReason: null isMine: true isSeller: false '201': description: >- Bid placed. Check order.status: running (filled), resting, or cancelled. content: application/json: schema: $ref: '#/components/schemas/CapacitySpotOrderEnvelope' example: order: orderId: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa orderBookId: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb gpuSlug: nvidia_h100_sxm side: bid orderType: limit pricePerGpuHourMicroUsd: 2500000 requestedGpus: 8 remainingGpus: 0 status: running cancelReason: null aggressorSide: bid listingId: eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee nodeId: 33333333-3333-4333-8333-333333333333 createdAt: '2026-10-14T18:30:00.000Z' filledAt: '2026-10-14T18:30:00.000Z' endedAt: null endReason: null isMine: true isSeller: false '400': description: Missing Idempotency-Key or invalid body. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: idempotency_key_required message: Send an Idempotency-Key header with this request. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: There is no order book for that GPU slug. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: order_book_not_found message: There is no spot market for that GPU type. '409': description: The Idempotency-Key was already used for a different request. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: idempotency_conflict message: That request key was already used for a different request. '422': description: >- gpus is not 1, 2, 4, or 8, orderType is unknown, or a limit has no positive price. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: invalid_gpus message: Spot orders take 1, 2, 4, or 8 GPUs. default: $ref: '#/components/responses/Error' components: schemas: CapacitySpotBidRequest: type: object required: - gpuSlug - gpus - orderType additionalProperties: false properties: gpuSlug: type: string description: Catalog GPU slug of the order book. gpus: type: integer enum: - 1 - 2 - 4 - 8 description: GPUs for one VM on one node. To buy N VMs, place N bids with N keys. orderType: type: string enum: - limit - market description: >- limit fills at or below your price or rests on the book until it fills or you cancel. market fills now at the best available ask or is cancelled. pricePerGpuHourMicroUsd: type: integer format: int64 minimum: 1 description: >- Required for limit bids; omit for market bids. The most you pay per GPU-hour, fees included, in integer micro-USD (1000000 is $1.00). CapacitySpotOrderEnvelope: type: object required: - order properties: order: $ref: '#/components/schemas/CapacitySpotOrder' Error: type: object properties: code: type: string detail: oneOf: - type: string - type: object required: - code - message properties: code: type: string message: type: string CapacitySpotOrder: type: object required: - orderId - side - status - isMine - isSeller properties: orderId: type: string format: uuid description: Order ID. A filled bid's reservation has this same ID. orderBookId: type: string format: uuid gpuSlug: type: - string - 'null' side: type: string enum: - bid - ask description: bid for your bids; ask for capacity your listings offer on the book. orderType: type: string enum: - limit - market pricePerGpuHourMicroUsd: type: - integer - 'null' format: int64 description: >- The order's own price: a bid's limit, or null for a market bid. A fill's price is on the reservation. requestedGpus: type: - integer - 'null' remainingGpus: type: - integer - 'null' status: type: string description: >- Bids: resting (waiting on the book), running (filled; the spot reservation is live), cancelled (never filled), or ended (a running reservation stopped). Asks: resting, exhausted, or cancelled. Handle unrecognized values. cancelReason: type: - string - 'null' description: >- For example unfilled_market_order, cancelled_by_owner, or cancelled_by_admin. aggressorSide: type: - string - 'null' enum: - bid - ask - null listingId: type: - string - 'null' format: uuid description: The listing that filled the bid. nodeId: type: - string - 'null' format: uuid description: The node the filled bid runs on. createdAt: type: - string - 'null' format: date-time filledAt: type: - string - 'null' format: date-time endedAt: type: - string - 'null' format: date-time endReason: type: - string - 'null' description: >- Why a running bid ended: stopped_by_buyer, stopped_by_seller, stopped_by_admin, preempted_by_reservation, listing_ended, payment_failed, or provisioning_failed. Handle unrecognized values. failure: type: - object - 'null' description: >- Customer-facing failure details for an ended order with a payment or provisioning failure. Visible only to the buyer and staff; derived from endReason. required: - code - message properties: code: type: string message: type: string isMine: type: boolean description: True when your organization placed this order. isSeller: type: boolean description: >- True when the order filled against, or is, capacity your organization listed. responses: Unauthorized: description: >- The credential is missing, invalid, revoked, or no longer belongs to a current organization member. Check the HTTP status before parsing the body. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The credential lacks access to this operation, or the organization requires approval. An API key does not bypass these checks. content: application/json: schema: $ref: '#/components/schemas/Error' Error: description: >- Unsuccessful request. Check HTTP status first. Errors may have detail.code/detail.message, a string detail and optional top-level code, or an empty/non-JSON body. 401: invalid credential; 403: access or approval required; 404: not visible or credentials not ready; 409: lifecycle conflict; 429: back off; 5xx: service failure. Inspect current state before retrying mutations. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: OrnnApiKey: type: http scheme: bearer bearerFormat: ornn_sk_... description: >- Create an organization API key in Account Settings > Developer. Do not send this key to the Kubernetes API server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.