---
title: "List admitted offers (public)"
method: GET
path: "/api/v1/offers"
tags: ["catalog"]
---

# List admitted offers (public)

`GET /api/v1/offers`

## Request

- Base URL: `https://amplerun-api.spiry.org`
- URL: `https://amplerun-api.spiry.org/api/v1/offers`
- Auth: none declared

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.

## Query parameters

- `cursor` string
- `limit` integer
- `template_id` string, uuid
- `fits_for` 'all'
- `sort` 'price_asc' | 'price_desc' | 'vram_desc' | 'reliability_desc' | 'uptime_desc' | 'newest' | 'verification' | 'net_desc' | 'tflops_desc' | 'ai_speed_desc'
- `verification_level` 'unverified' | 'auto_verified' | 'manually_verified'
- `include_unverified` boolean
- `min_bandwidth_mbps` integer
- `max_rate_micro_per_hour` string: Unsigned base-10 integer as string; never a float.
- `gpu_count` integer
- `model` string
- `tier` 'container' | 'inference'
- `backend` 'cuda' | 'rocm' | 'sycl' | 'vulkan' | 'metal'
- `continent` 'af' | 'an' | 'as' | 'eu' | 'na' | 'oc' | 'sa' | 'americas' | 'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA': A continent code, case-insensitive, or americas (North and South America).
- `near` 'af' | 'an' | 'as' | 'eu' | 'na' | 'oc' | 'sa' | 'americas' | 'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA': A continent code, case-insensitive, or americas (North and South America).

## Response `200`

Page of offer summaries.

- object
  - `items` OfferSummary[], required
    - `offer_id` string, uuid, required
    - `machine_id` string, uuid, required
    - `observed_at` string, date-time, required
    - `offer_version` string, required: Unsigned base-10 integer as string; never a float.
    - `expected_version` string, required: Unsigned base-10 integer as string; never a float.
    - `readiness` 'ready' | 'provisioning' | 'unavailable', required
    - `total_rate_micro_per_hour` string, required: Unsigned base-10 integer as string; never a float.
    - `included_quotas` object, required
      - `included_disk_gib` integer, required
      - `included_egress_gib` integer, required
    - `available_from` string, date-time, required
    - `available_until` string, date-time, required
    - `maintenance_windows` object[], required
      - `starts_at` string, date-time, required
      - `ends_at` string, date-time, required
      - `reason` string, required
    - `gpu_count` integer
    - `model` string
    - `vram_bytes` string: Unsigned base-10 integer as string; never a float.
    - `region` string
    - `country` string: Additive. ISO 3166-1 alpha-2 country of the machine, read by the controller from the agent's request country as reported by the trusted proxy (never from host input). Absent when unknown.
    - `continent` 'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA': Additive. Continent derived from country: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America. Absent when the country is unknown.
    - `ram_bytes` string: Unsigned base-10 integer as string; never a float.
    - `disk_bytes` string: Unsigned base-10 integer as string; never a float.
    - `measured_bandwidth_mbps` integer: netfacts lane. Measured DOWNLOAD rate in Mbps; additive. Absent = never measured (never 0).
    - `net_up_mbps` integer: netfacts lane. Measured UPLOAD rate in Mbps; rides the same measurement as measured_bandwidth_mbps.
    - `net_latency_ms` integer: netfacts lane. Median HTTPS latency in ms from the same measurement.
    - `speedtest_at` string, date-time
    - `tflops_bf16` number: AI Speed. Measured dense BF16 matmul TFLOPS per GPU (the MIN across the machine's GPUs); additive. Absent = never measured (never 0).
    - `tflops_total` number: AI Speed. tflops_bf16 x gpu_count, computed, one decimal. Absent with tflops_bf16 or gpu_count.
    - `mem_bw_gbps` number: AI Speed. Measured device memory bandwidth in GB/s per GPU (the MIN across the machine's GPUs). Absent = never measured (never 0).
    - `ai_speed` integer: AI Speed. round(100*sqrt((tflops_bf16/165.2)*(mem_bw_gbps/1008))); RTX 4090 = 100. Absent unless both figures were measured.
    - `bench_at` string, date-time
    - `bench_flag` 'unverified_spec': AI Speed. The GPU has no datasheet row to check the figures against.
    - `disk_free_bytes` string: Unsigned base-10 integer as string; never a float.
    - `uptime_s` string: Unsigned base-10 integer as string; never a float.
    - `gpu_utilization_pct` number: Additive. Live GPU load, the PEAK across the machine's devices, from the latest telemetry sample. Absent under the same rules as disk_free_bytes, and when no device reported utilisation. 0 means measured idle.
    - `telemetry_at` string, date-time
    - `template_compatibility` string[]
    - `manifest_hash` string
    - `fit` TemplateFit: D-19(c) per-offer fit verdict for a template, computed server-side from vram_fit against measured device VRAM. reason is human-readable and non-empty when fits is false.
      - `fits` boolean, required
      - `reason` string, required
    - `fits_template_ids` UUID[]: Additive. Present only when the request carried fits_for=all; the ids of every published template that fits this offer (the same rule as fit).
    - `platform_fee_bps` integer: Additive. Platform fee frozen into this offer version, in basis points (500 = 5%), taken out of each charge.
    - `verification_level` 'unverified' | 'auto_verified' | 'manually_verified': Additive. How the machine's hardware claims were verified.
    - `admitted` boolean: Additive. Whether the machine has passed admission (a passed qualification for its current manifest). false is an unverified listing: shown in the catalog, never quoted or reserved (409 CONFLICT).
    - `tier` 'container' | 'inference': Additive (D-23). container: SSH containers under the launch profile. inference: managed models on a signed, hash-pinned runtime with no renter code, reached over the host's outbound session (community inference: don't send sensitive data).
    - `backends` string[]: Additive. Backends the machine's devices serve, in preference order (cuda > rocm > sycl > vulkan > metal). A template runs here with the first one it has a runtime for.
    - `reliability` object: Additive. Approximate reliability score from machine fields only (no per-job joins on the catalog path).
      - `score` number, required
      - `stars` string, required
      - `band` string, required
      - `approximate` boolean, required
    - `availability_class` 'dedicated' | 'interruptible': D-22. dedicated (the default) is never preempted. interruptible is sold only from idle or co-listed hosts: the host may take the machine back after preemption_notice_s seconds of notice, and billing stops at the notice.
    - `preemption_notice_s` integer, nullable: D-22. Notice in seconds (SIGTERM plus /work/.amplerun-preempt) before the host stops an interruptible rental; null for dedicated.
    - `interruption_estimate` InterruptionEstimate: D-22, interruptible offers only. Plain observed counts, never a prediction. A run is one continuous period in which the host reported the machine offerable (from heartbeats); it counts when it ended, or has already lasted horizon_h. uninterrupted is null below the sample gate (20 runs): not enough history.
      - `runs` integer, required: Most recent decided runs counted (at most 40).
      - `uninterrupted` integer, nullable, required: Of those runs, how many lasted horizon_h without interruption; null below the sample gate.
      - `horizon_h` integer, required
      - `computed_at` string, date-time, required
      - `summary` string, required: The counts in words, e.g. "34 of the last 40 runs lasted 4 h without interruption" or "Not enough history (12 runs so far)".
  - `next_cursor` string, nullable, required

## Other responses

- `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.

---

[API](https://skmtc.dev/amplerun/apis/amplerun-business-api.md) · [All operations](https://skmtc.dev/amplerun/apis/amplerun-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/amplerun/apis/amplerun-business-api/revisions/40944687fa52?raw)