> Source: https://vitna.ai/docs/api/v1/prices/spreads
> Raw Markdown: https://vitna.ai/docs/api/v1/prices/spreads.md
> Corpus index: https://vitna.ai/llms.txt

# Spreads

What several providers charge for the same product, cheapest first, with the
percentage between the low and the high.

```
GET /api/v1/spreads/{class}/{product}
```

```bash
curl https://vitna.ai/api/v1/spreads/compute/h100-sxm
curl "https://vitna.ai/api/v1/spreads/model/kimi-k3?dimension=output_per_mtok"
```

## Parameters

| Parameter | In | Meaning |
|---|---|---|
| `class` | path | `model`, `tooling`, `retrieval` or `compute` |
| `product` | path | Product slug, lowercased and dashed |
| `dimension` | query | Which meter. Optional. |

Product slugs come from the sku's `attrs`, not from a separate table. `H100 SXM`
is `h100-sxm`.

## Default dimension

Omitting `dimension` gives the one the boards draw:

| Class | Default |
|---|---|
| `model` | `input_per_mtok` |
| `tooling` | `tool_call_per_1k` |
| `retrieval` | `embed_per_mtok` |
| `extraction` | `page_ocr` |
| `compute` | `gpu_hour_on_demand` |

## Response

```json
{
  "class": "compute",
  "product": "H100 SXM",
  "productSlug": "h100-sxm",
  "dimension": "gpu_hour_on_demand",
  "unit": "USD per GPU-hour",
  "providerCount": 6,
  "minUsd": 1.99,
  "maxUsd": 3.29,
  "spreadPct": 65,
  "freshestAt": "2026-08-23T08:00:11.402Z",
  "stalestAt": "2026-08-22T19:00:04.118Z",
  "anyStale": false,
  "providers": [ { "provider": "...", "skuSlug": "...", "amountUsd": 1.99, "derived": false, "stale": false, "fetchedAt": "...", "evidenceSha256": "..." } ],
  "dimensions": ["gpu_hour_on_demand"],
  "meta": { "generatedAt": "...", "source": "database" }
}
```

`spreadPct` is `(max - min) / min`, as a rounded whole percent. It is expressed
against the cheapest seller, so 65 means the dearest costs 65 percent more than
the cheapest, not that it is 65 percent of it.

`dimensions` lists every meter this product has a spread for, so a caller can
discover what else to ask for without a second request.

## Two providers minimum

A dimension with fewer than two priced providers has no spread and is omitted.
A single-seller meter is a price, not a spread, and reporting a zero percent
spread for it would suggest agreement between sellers that do not exist.

## Cache writes

A spread on `cache_write_5m_per_mtok` or `cache_write_1h_per_mtok` carries a
`blockNote`. Sellers cache in blocks of a size each one chooses, so two equal
rates per million tokens at one retention window need not buy the same caching.
No other meter carries the field. See
[what a cache write can and cannot be set against](../../../concepts/dimension.md#what-a-cache-write-can-and-cannot-be-set-against).

## Errors

| Status | Code | Cause |
|---|---|---|
| 404 | `unknown_class` | Not a registered class |
| 404 | `unknown_product` | No product by that slug in the class |
| 404 | `unknown_dimension` | Product exists, is not metered that way. The message lists the ones it has. |

## Two paths, one shape

With a database the answer comes from the SQL view; without one it is computed
from the committed snapshot. The shapes are identical by design, so the site and
the API cannot disagree about a figure. `meta.source` is the only way to tell
which path answered.

## Caching

`public, max-age=60, stale-while-revalidate=3600`.
