---
title: "Cross-commodity ratio time-series — date-joined daily closes (Pro+)"
method: GET
path: "/v1/ratios"
tags: ["ratios"]
---

# Cross-commodity ratio time-series — date-joined daily closes (Pro+)

`GET /v1/ratios`

Paginated cross-commodity ratio series from the canonical price_bars store.

Results are ordered DESC by date (newest first). Paginate via
next_cursor — pass it as ?cursor= on the next request. When next_cursor
is null the result is exhausted. Empty range returns 200 with points: [].

A date where either leg has no bar is absent — no forward-fill, no
fabrication (Invariant #1 honesty).

Tier depth gates (same as /v1/bars 1d):
- Free:  30 days (403 plan_gated)
- Basic: 1 year  (403 plan_gated)
- Pro+:  full history
All pairs require Pro+ (all pairs involve a non-XAU or non-spot leg).

## Query parameters

- `pair` string, required — Pair slug. Supported: gold-silver, gold-platinum, silver-platinum, gold-palladium, gld-xau. Alternatively pass numerator+denominator symbols directly.
- `from` string, required — ISO-8601 start (inclusive).
- `to` string, required — ISO-8601 end (inclusive).
- `limit` integer — Max points per page (1-10000). Default 100.
- `cursor` string, nullable — Opaque keyset pagination cursor from a prior response's next_cursor. When set, returns points older than the cursor within the from/to window.

## Response `200`

Successful Response

- RatiosResponse — Response envelope for GET /v1/ratios. Keyset pagination via next_cursor. When next_cursor is null, the result is exhausted (no more pages). An empty points list with next_cursor=null is the canonical empty-range response (200, never 404). Results are ordered DESC by date (newest first), mirroring /v1/bars.
  - `pair` string, required — The pair slug (e.g. 'gold-silver', 'gold-platinum', 'gld-xau'). Echoed from the request for self-describing responses.
  - `numerator` string, required — Resolved numerator instrument symbol (e.g. 'XAU/USD').
  - `denominator` string, required — Resolved denominator instrument symbol (e.g. 'XAG/USD').
  - `interval` string — Bar interval. Currently always '1d' (intraday ratios out of scope at launch).
  - `points` RatioPoint[], required — Ratio data points, newest-first (DESC by date).
    - `date` string, required — Bar date in YYYY-MM-DD format (UTC midnight = bar_start_utc). Only emitted when both numerator and denominator have a settled bar for this date — no forward-fill, no fabricated rows.
    - `ratio` string, required — numerator_close / denominator_close as a decimal string (4 dp). Example: '88.1234'. Never null — a date without both legs is simply absent from the series.
    - `numerator_close` string, required — Closing price of the numerator instrument as a decimal string.
    - `denominator_close` string, required — Closing price of the denominator instrument as a decimal string.
  - `next_cursor` string, nullable — Opaque cursor for the next page. Pass as ?cursor= on the next request. Null when the result is exhausted. Encoding: base64url of the date string ('YYYY-MM-DD') of the last point in this page.
  - `meta` RatiosMeta, required — Metadata block in RatiosResponse. Mirrors BarsMeta.
    - `tier` string, required
    - `count` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/goldprice/apis/gold-api.md) · [All operations](https://skmtc.net/goldprice/apis/gold-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goldprice/gold-api/revisions/7885a141754c/schema)