GET /api/v1/offers

Operation: listOffers.

List admitted offers (public)

Listed offers on available, admitted machines with a heartbeat in the last 90 seconds; only these can be reserved. Server-side filters are model, gpu_count, max_rate_micro_per_hour, verification_level, continent and template_id; sort defaults to price_asc, and near puts one continent’s machines first. There is no VRAM, region, RAM, disk or bandwidth filter: each item carries vram_bytes, region, ram_bytes and disk_bytes when measured, for client-side filtering. With template_id (D-19(c)) every item carries a server-computed fit object. No cached public responses.

Endpoint

GET https://amplerun-api.spiry.org/api/v1/offers

Authentication

No default Bearer requirement is declared for this operation. Read its description for wallet signatures, host enrollment or other specialized proofs.

Parameters

Name	Location	Presence	Type	Description
cursor	query	Optional	string	Opaque pagination cursor from a previous response.
limit	query	Optional	integer
template_id	query	Optional	UUID	Compute per-offer fit against this template’s vram_fit (D-19(c)). The template’s id (UUID), not its slug; resolve a slug with GET /api/v1/templates/{templateId}. Unknown or unpublished template -> 404, a slug -> 422.
fits_for	query	Optional	“all”	Additive. all adds fits_template_ids to every item, the ids of every published template that fits that offer under the same rule as template_id, in one read. Any other value -> 422.
sort	query	Optional	“price_asc” / “price_desc” / “vram_desc” / “reliability_desc” / “uptime_desc” / “newest” / “verification” / “net_desc” / “tflops_desc” / “ai_speed_desc”	Keyset sort order; an unknown value falls back to price_asc.
verification_level	query	Optional	“unverified” / “auto_verified” / “manually_verified”	Only machines at exactly this verification level.
include_unverified	query	Optional	boolean	Also list machines that have not passed admission yet.
min_bandwidth_mbps	query	Optional	integer	netfacts lane. Only machines whose MEASURED download rate is at least this; machines that never measured are excluded (they cannot claim a rate).
max_rate_micro_per_hour	query	Optional	MicroAmount	Only offers whose total machine rate is at or below this amount.
gpu_count	query	Optional	integer	Only offers whose machine manifest lists at least this many devices.
model	query	Optional	string	Case-insensitive substring match on the first device model in the manifest.
tier	query	Optional	“container” / “inference”	Only machines of this tier (D-23).
backend	query	Optional	“cuda” / “rocm” / “sycl” / “vulkan” / “metal”	Only machines with a device serving this backend.
continent	query	Optional	ContinentFilter	Only machines on this continent (americas = NA + SA). Machines with an unknown location are excluded. Any other value -> 422.
near	query	Optional	ContinentFilter	Order this continent’s machines first (lower latency), then by sort. Keeps every other machine. Any other value -> 422.

Responses

200

Page of offer summaries.

application/json

Field	Type	Presence	Description
items	array of OfferSummary	Required
next_cursor	string or null	Required

{
  "type": "object",
  "required": [
    "items",
    "next_cursor"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OfferSummary"
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

default

Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.

application/json

Field	Type	Presence	Description
error	object	Required

{
  "$ref": "#/components/schemas/ErrorEnvelope"
}

Static request outline

Replace path/query placeholders and provide the required JSON body, headers and credential from the sections above. This is a request outline, not a command that chooses an amount or starts a rental for you.

curl --request GET 'https://amplerun-api.spiry.org/api/v1/offers'

Schema definitions · Download OpenAPI · Authentication · Errors and recovery