List Compute Offers

Find currently available machines that satisfy hardware requirements and an optional price ceiling. All supplied filters are combined; use the bracketed query parameter names shown below.

Each result groups nodes with the same public hardware summary, region, and quoted whole-node execution rate. availability.available_count counts matching nodes; pricing.hourly_rate_usd is USD per hour for one entire node, including all of its GPUs. GPU counts describe installed hardware, not a number of GPUs reserved from a larger machine. A model filter requires at least one matching GPU; inspect hardware_summary.gpu_models for mixed-model machines.

Examples (query values must be URL-encoded by your HTTP client):

• Compare 1-2 GPU machines with at least 8 CPU cores, 24 GiB VRAM per GPU, and 64 GiB RAM for at most $1.25 per machine-hour: GET /v1/compute/offers?filter[min_gpu_count]=1&filter[max_gpu_count]=2&filter[cpu_count]=8&filter[min_vram_gb]=24&filter[min_ram_gb]=64&filter[max_hourly_rate_usd]=1.25&sort=hourly_rate_usd.
• Require exactly 2 GPUs: filter[min_gpu_count]=2&filter[max_gpu_count]=2. A minimum of 2 alone also allows machines with more GPUs.
• Find CPU-only machines: filter[max_gpu_count]=0&filter[cpu_count]=8; omit GPU model and VRAM requirements.
• Discover model UUIDs via GET /v1/gpu-registry, then add filter[gpu_registry_uuid]=<uuid> for exact model selection. Add filter[allowed_region_codes]=us-west-1,us-west-2 to narrow regions. Workspace and consumer-profile geography restrictions still apply.

Pagination uses page (default 1) and limit (default 10, maximum 50); total counts matching offer groups after filtering. Results are a snapshot and do not reserve capacity or lock a price. Refresh discovery before submission. Create a job with POST /v1/jobs or cook a recipe with POST /v1/job-recipes/{uuid}/cook, carrying over the GPU bounds, model, memory, storage, and region requirements; map the discovery cpu_count filter to the request’s min_cpu_count. These requests do not accept offer_id or max_hourly_rate_usd as a reservation or budget constraint.

GET /v1/compute/offers

List Compute Offers

cURL

curl --request GET \
  --url https://api.dispersed.com/v1/compute/offers

200

{
  "data": [
    {
      "availability": {
        "available_count": 1,
        "status": "AVAILABLE"
      },
      "hardware_summary": {
        "cpu_cores": 123,
        "gpu_count": 123,
        "gpu_model_label": "<string>",
        "gpu_models": [
          {
            "count": 123,
            "gpu_registry_uuid": "<string>",
            "min_vram_gib": 123,
            "name": "<string>"
          }
        ],
        "gpu_registry_uuid": "<string>",
        "min_gpu_vram_gib": 123,
        "ram_gib": 123,
        "storage_gib": 123
      },
      "offer_id": "<string>",
      "pricing": {
        "hourly_rate_usd": 123,
        "network_pricing_policy_uuid": "<string>",
        "quoted_at": "2023-11-07T05:31:56Z"
      },
      "region_code": "us-west-2"
    }
  ],
  "limit": 123,
  "page": 123,
  "total": 123
}

Query Parameters

limit · integer

Required range: 1 <= x <= 50

Example:

1

page · integer

Required range: 1 <= x <= 9007199254740991

Example:

1

sort · string

Sort by hourly_rate_usd (default, cheapest first), gpu_count, cpu_cores, ram_gib, or min_gpu_vram_gib. Prefix with - for descending order, for example -gpu_count. Sorting occurs after all hardware, region, and price filters.

Example:

"hourly_rate_usd"

filter[min_gpu_count] · integer | null

Inclusive minimum total GPUs installed on each node, including all GPU models. Omit or use 0 for no minimum. Set min_gpu_count and max_gpu_count to the same value for an exact count.

Required range: x >= 0

Example:

"1"

filter[max_gpu_count] · integer | null

Inclusive maximum total GPUs installed on each node. Omit for no upper limit. Use 0 for CPU-only nodes. Must be greater than or equal to min_gpu_count (or the legacy gpu_count alias).

Required range: x >= 0

Example:

"2"

filter[cpu_count] · integer | null

Minimum total CPU cores per node. This discovery filter corresponds to min_cpu_count when creating or cooking a job.

Required range: x >= 0

Example:

"8"

filter[gpu_count] · integer | null

Legacy alias for min_gpu_count; it is a minimum, not an exact count. If both are provided, their values must match.

Required range: x >= 0

Example:

"1"

filter[gpu_name] · string

Fuzzy GPU model-name match. A node must contain at least one matching GPU; count bounds still apply to all GPUs on the node. Prefer gpu_registry_uuid for exact model selection.

Example:

"RTX 4090"

filter[gpu_registry_uuid] · string<uuid>

Exact GPU model UUID from GET /v1/gpu-registry. A node must contain at least one GPU of this model; count bounds apply to all GPUs on the node. Takes precedence over gpu_name.

Example:

"019582a6-27fc-731d-af0a-594f04d6d0d5"

filter[max_hourly_rate_usd] · number | null

Inclusive USD-per-hour ceiling for the quoted execution rate of the entire node, not a per-GPU rate. Applied together with hardware and region filters, before sorting and pagination. Omit for no price ceiling. This discovery filter does not set a job spending limit or lock a future price.

Required range: x >= 0

Example:

"1.25"

filter[min_vram_gb] · integer | null

Minimum VRAM per GPU, not the sum across GPUs. Despite the _gb name, uses GiB (1024^3 bytes) with a 5% capacity tolerance; displayed GiB values are rounded down.

Required range: x >= 0

Example:

"24"

filter[min_ram_gb] · integer | null

Minimum total RAM per node in GiB (1024^3 bytes), with a 5% capacity tolerance. Displayed ram_gib is rounded down.

Required range: x >= 0

Example:

"64"

filter[min_storage_gb] · integer | null

Minimum total storage capacity per node in GiB (1024^3 bytes), with a 5% capacity tolerance. This is reported total capacity, not free disk space.

Required range: x >= 0

Example:

"100"

filter[allowed_region_codes] · string

Restricts offers to nodes whose response region_code is in this comma-separated allowlist. This is intersected with the requester`s workspace and consumer-profile policies.

Example:

"us-west-1,us-west-2"

filter[workload_image] · string

Docker image used to apply workload-specific node cooldown exclusions. Omit for generic catalog behavior.

Example:

"ubuntu"

filter[workload_tag] · string

Docker image tag used with workload_image for workload-specific node cooldown exclusions. Defaults to latest when omitted.

Example:

"24.04"

Response

200

application/json

Paginated groups of available machines satisfying all supplied filters, with whole-node hourly quotes and matching-node counts.

data · object[] · required

Show child attributes

limit · integer · required

page · integer · required

total · integer · required