---
title: "OHLCV bar history — cursor-paginated, real data, is_closed label"
method: GET
path: "/v1/bars"
tags: ["bars"]
---

# OHLCV bar history — cursor-paginated, real data, is_closed label

`GET /v1/bars`

Paginated OHLCV bar history from the canonical price_bars store.

Results are ordered DESC by bar_start (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 bars: [].

Tier depth gates:
- Free:  30 days
- Basic: 1 year
- Pro+:  full history (daily back to 1996 for XAU/USD; intraday from 2006)

Intraday intervals (1m, 5m, 15m, 30m, 1h, 2h, 4h) require Pro+.

## Query parameters

- `symbol` string, required — Symbol in slash or dash form. E.g. "XAU/USD", "XAU-USD-SPOT", "GLD".
- `interval` string — Bar interval. One of: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1d.
- `from` string, required — ISO-8601 start (inclusive).
- `to` string, required — ISO-8601 end (inclusive).
- `limit` integer — Max bars per page (1-10000). Default 100.
- `cursor` string, nullable — Opaque keyset pagination cursor from a prior response's next_cursor. When set, returns bars older than the cursor within the from/to window.

## Response `200`

Successful Response

- BarsResponse — Response envelope for GET /v1/bars. Keyset pagination via next_cursor. When next_cursor is null, the result is exhausted (no more pages). An empty bars list with next_cursor=null is the canonical empty-range response (200, never 404).
  - `symbol` string, required — The requested symbol (e.g. 'XAU/USD', 'GLD').
  - `interval` string, required — The requested interval (e.g. '1d', '15m').
  - `bars` Bar[], required — OHLCV bars, newest-first (DESC by bar_start).
    - `bar_start` string, required — Bar open timestamp, ISO-8601 UTC with Z suffix (e.g. "2026-06-15T00:00:00Z"). The bar covers the half-open interval [bar_start, bar_start + interval).
    - `open` string, nullable — Open price as decimal string. Null only on data gaps (never fabricated).
    - `high` string, nullable — High price as decimal string.
    - `low` string, nullable — Low price as decimal string.
    - `close` string, nullable — Close price as decimal string.
    - `volume` string, nullable — Trading volume as decimal string. Null for spot instruments (XAU/USD, XAG/USD — no consolidated spot volume). Real for futures (GC, SI, HG) and ETFs (GLD). Never 0, never fabricated.
    - `is_closed` boolean, required — True if the bar's time window has ended and the OHLC values are final (settled). False for the currently-forming bar (provisional).
  - `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 bar_start_utc ISO-8601 string of the last bar in this page.
  - `meta` BarsMeta, required — Metadata block in BarsResponse. source_id is a PAGE-SCOPED provenance summary derived from the bars in this page — NOT a per-bar attribute. It equals the source_id of the first bar in the page, or "mixed" if the page spans multiple source_ids (e.g. a range that crosses from CSV history into a live Pyth feed). It is non-authoritative for mixed pages: consumers wanting per-bar provenance should wait for a future version that exposes bar.source_id per-bar. That per-bar field is a reserved future decision (flagged in the §9.4 public-surface audit); do NOT add it to the current Bar wire shape without a version bump. Examples: 'csv_xau_15m_v1', 'csv_xau_rollup_v1', 'lse_gld', 'mixed'. Null when bars list is empty.
    - `tier` string, required
    - `count` integer, required
    - `source_id` string, nullable — Provenance tag from the price_bars store. Examples: 'csv_xau_15m_v1', 'csv_xau_rollup_v1', 'lse_gld', 'pyth_live'. Null when bars list is empty.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `429` — Too Many Requests
- `503` — Service Unavailable

---

[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)