GPU Cloud API
The GPU Cloud API finds GPU offers, prices them, and rents GPU containers, VMs, and bare metal servers. The same API manages the instances after you rent them. For workload types, spot instances, statuses, and billing, see GPU Cloud concepts.
- Base URL:
https://api.fluence.dev. Every path on this page starts with/v3/gpu. - OpenAPI document: api.fluence.dev/v3/gpu/openapi.json
The GPU endpoints have their own OpenAPI document. Their error body has code, error, and details, which differs from the rest of the Fluence API. See Errors.
Authentication and permissions
Send an API key in the X-API-KEY header, or an access token in Authorization: Bearer. See Authentication.
| To | Scope |
|---|---|
| List images, read offers, get quotes, and read your instances | gpu:read |
Create, change, and delete instances, and everything that gpu:read allows | gpu:write |
When you create a key in the Fluence Console, give it View & manage access to GPU containers or GPU VMs & bare metal. See Settings. These options give akash:write and spheron:write, the scopes of the legacy GPU API. A key with either scope also works with /v3/gpu, for reading and for changes.
GET /v3/gpu/offers and GET /v3/gpu/offers/{id} also work without credentials. Without credentials, the list shows only offers that you can rent now. The OpenAPI document needs no credentials either. Every other endpoint returns 401 with unauthenticated without credentials.
Endpoints
Offers
| Method | Path | What it does |
|---|---|---|
GET | /v3/gpu/offers | Lists offers: one placement each, with hardware, price, and availability |
GET | /v3/gpu/offers/{id} | Returns one offer |
GET | /v3/gpu/offer-groups | Groups offers by GPU configuration, with the lowest price of each group |
GET | /v3/gpu/offer-facets | Lists the values you can filter by, such as GPU models, countries, and providers, with counts |
GET | /v3/gpu/offer-picks | Returns the cheapest offers with at least the GPU memory you need |
POST | /v3/gpu/instance-quotes | Shows which offer a request would get and at what price, without renting |
Instances
| Method | Path | What it does |
|---|---|---|
POST | /v3/gpu/instances | Creates an instance |
GET | /v3/gpu/instances | Lists your instances |
GET | /v3/gpu/instances/{id} | Returns an instance |
GET | /v3/gpu/instances/by-idempotency-key | Finds an instance by the Idempotency-Key it was created with |
PATCH | /v3/gpu/instances/{id} | Renames an instance or changes the container of a running one |
DELETE | /v3/gpu/instances/{id} | Ends an instance |
GET | /v3/gpu/instances/{id}/logs | Returns the last lines of the instance output |
GET | /v3/gpu/instances/{id}/events | Returns recent provider events of the instance |
Images and the API document
| Method | Path | What it does |
|---|---|---|
GET | /v3/gpu/default-images | Lists predefined container images with their ports, environment variables, and SSH user |
GET | /v3/gpu/openapi.json | Returns the OpenAPI document of /v3/gpu |
The OpenAPI document also has volume endpoints. Volumes are not available yet. See Volumes.
Find an offer
An offer is one placement that you can rent. It names a provider, a region, a GPU model and count, the rest of the machine, a rental type, and a price. Each offer has a workload: container, vm, or baremetal.
Choose the call that matches what you know:
- You know how much GPU memory you need: call
GET /v3/gpu/offer-pickswithworkloadandminVramGib, the memory of each GPU in GiB. It returns up to 10 of the cheapest offers, 3 by default. Each item hasrequirementsthat you pass to the quote and to the create request unchanged. If no offer fits,itemsis empty,rejectedsays why the other offers do not fit, andlargestOnSalegives the largest GPU memory and GPU count on sale. - You want to compare GPU models: call
GET /v3/gpu/offer-groups. Each group has its lowest price andrequirementsfor the quote. To create from a group, also setofferIdto the group'scheapestOfferId, or setmaxPricePerHour. - You want to see every placement: call
GET /v3/gpu/offers.
GET /v3/gpu/offers, GET /v3/gpu/offer-groups, and GET /v3/gpu/offer-facets take the same filters:
| Filter | What it matches |
|---|---|
workload | container, vm, or baremetal |
rentalType | on_demand or spot. Without it, only on-demand offers are listed. |
gpuVendor, gpuModel, gpuInterface | The GPU as offers name it, for example nvidia, h100, sxm. Case does not matter. |
gpuVramGib, minGpuVramGib | Memory of each GPU in GiB, exact or at least |
gpuCount, minGpuCount | GPUs per machine, exact or at least |
minVcpu, minMemoryGib, minStorageGib | Machine size, at least |
country, regionLabel, provider | Location. country is a two-letter ISO code. provider takes several names separated by commas. |
hostTier | dedicated, shared, or unknown |
cpuArchitecture | x86_64, arm64, or unknown |
maxPricePerHour | The highest price per instance-hour in USD, as a decimal string, for example 0.50 |
available | false also lists offers without capacity left. Without credentials, only offers on sale are listed. |
q | Text in the GPU vendor, GPU model, provider, or region label |
To sort, set sort to price, vram, vcpu, memory, storage, or availability, and order to asc or desc. Without sort, the cheapest offers come first.
Name GPU models exactly as offers name them, for example rtx4090 or h100. GET /v3/gpu/offer-facets lists the models on sale. A filter with an unknown model returns an empty list. In a quote or a create request, an unknown model in requirements.gpu.model returns invalid_input.
curl "https://api.fluence.dev/v3/gpu/offers?workload=vm&rentalType=spot&minGpuVramGib=80"
Read an offer
Besides the hardware and the price, an offer has these fields:
offerKind:provider_skuis an item of a provider catalog, andhost_offeris one host.market_profileis an Akash offer that fixes the hardware profile and the highest bid, but not the host. Akash picks the host from bids when you create the instance.hostTier:dedicated,shared, orunknown.region,dataCenter, andorigin: where the machine runs.topology: GPU links, such as NVLink.provisioning: how long the instance usually takes to be ready, intypicalSeconds,upperSeconds, or both. It can benull.availability:statusisavailable,limited,sold_out, orunknown.lastOutOfStockAtis the last time the provider refused this offer for lack of capacity. Such an offer stays on sale, and the next launch can succeed.capabilities: what an instance of the offer supports.logs,events, andupdatesay whether you can read logs and events and change the container.portProtocols,portRequired,environment, andprivateRegistrylimit the container settings. See Create the instance.osImages: the OS images that a VM or bare metal offer accepts. An empty list means the provider takes any name, and a wrong name fails only at the provider.preemption: only for spot offers.noticeSecondsis the warning the provider gives before it takes the machine back, and0means no warning.dataSurvivessays whether the disk survives.signalisexplicitwhen the provider reports the take-back, andinferredwhen Fluence detects it from the machine stopping.groupKey: the offer group of the offer, as inGET /v3/gpu/offer-groups.
Offer prices
Every offer has a price. Here is the price of an 8 × RTX 4090 VM offer from GET /v3/gpu/offers:
{
"currency": "USD",
"unit": "instance",
"perHour": "4.2240",
"gpuHour": "0.5280",
"stepSeconds": 60,
"perStep": "0.0704",
"minimumPeriodSeconds": 1200,
"minimumCharge": "1.4080",
"components": [{ "kind": "gpu", "perHour": "4.2240" }]
}
perHouris the full price of the instance per hour in USD.gpuHouris the same price per GPU, so you can compare offers with different GPU counts.stepSecondsis the billing step, andperStepis the price of one step.minimumChargeis the least you pay for an instance that starts running. It coversminimumPeriodSecondsof running time.
Amounts are decimal strings. See Billing model.