> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polaris.supply/llms.txt
> Use this file to discover all available pages before exploring further.

# OHLCV

> Query venue-published OHLCV updates over REST or derive UTC-aligned bars with the SDK.

Use `GET /ohlcv` to read venue-published candle updates, including updates to an open candle. Several REST rows can share the same candle interval and open time. The SDK's `ohlcv()` method instead derives one UTC-aligned bar per interval from standardized trades; see [SDK-derived bars](#sdk-derived-bars).

## Request

```bash theme={null}
curl "https://api.polaris.supply/ohlcv?source=binance&market=BTC-USDT&interval=1m&limit=2"
```

### Query parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `source` | `string` | No | Optional exact source identifier |
| `market` | `string` | No | Optional exact normalized routing market across sources |
| `instrument` | `string` | No | Exact venue-native instrument |
| `interval` | `string` | No | Exact canonical candle interval, such as 1m or 1h |
| `start` | `integer` | No | Inclusive candle open time in Unix milliseconds. With no end, queries through now. Anonymous requests must start within the rolling last hour; older history requires a Polaris API key. |
| `end` | `integer` | No | Inclusive candle open time in Unix milliseconds. With no start, queries the preceding hour, clamped to the public cutoff for anonymous requests. Older history requires a Polaris API key. |
| `limit` | `integer` | No | Page size; defaults to 200 and values above 1000 are capped |
| `cursor` | `string` | No | Opaque keyset cursor bound to the filters and candle-time range; anonymous continuation skips rows that have aged beyond the last hour |

## Access and behavior

`start` and `end` are inclusive candle open times in Unix milliseconds, not collector times. Rows are ordered by candle open time with stable event tie-breakers. With no bounds, the API queries windows opened in the latest hour anonymously; older windows require a Polaris API key. `interval` is an exact canonical value such as `1m` or `1h`. Anonymous reads are capped at 1 GiB per request and two concurrent queries per API replica.

## Response

| Field | Type | Required | Description |
| - | - | - | - |
| `has_more` | `boolean` | Yes | — |
| `items` | `OhlcvEventItem[]` | Yes | — |
| `next_cursor` | `string / null` | No | — |

### `items[]` fields

| Field | Type | Required | Description |
| - | - | - | - |
| `base_volume` | `number / null` | No | — |
| `close` | `number` | Yes | — |
| `close_timestamp` | `integer / null` | No | — |
| `collector_timestamp` | `integer` | Yes | — |
| `event_id` | `string` | Yes | — |
| `exchange_timestamp` | `integer / null` | No | — |
| `high` | `number` | Yes | — |
| `instrument` | `string / null` | No | — |
| `interval` | `string` | Yes | — |
| `is_closed` | `boolean / null` | No | — |
| `low` | `number` | Yes | — |
| `market` | `string` | Yes | — |
| `open` | `number` | Yes | — |
| `open_timestamp` | `integer` | Yes | — |
| `quote_volume` | `number / null` | No | — |
| `schema_version` | `integer` | Yes | — |
| `source` | `string` | Yes | — |
| `source_capture_id` | `string` | Yes | — |
| `trade_count` | `integer / null` | No | — |

These are flat, venue-published observations. They are not the SDK's aggregated trade bars.

## REST pagination

Pass `next_cursor` as `cursor` with the same filters. Stop when `has_more` is false, or when `next_cursor` is null for endpoints without `has_more`. A cursor is opaque; do not edit or reuse it with different filters.

## REST errors

The OpenAPI contract lists `400`, `401`, `422`, `429`, `503`. Error responses use `error.code`, `error.message`, and `error.resolution`. Narrow an expensive query after `422`. Follow `Retry-After` after `429`.

For the machine-readable contract, see the [OpenAPI document](https://api.polaris.supply/openapi.json).

## SDK-derived bars

Use `client.ohlcv()` when you need interval-aligned bars derived from standardized trade data. Boundaries are fixed to UTC intervals, which makes cross-venue joins reproducible. The SDK's `to` bound is exclusive, while the REST `end` bound is inclusive.

### Method and parameters

```python theme={null}
ohlcv(source, market, from_, to, interval, format=None)
```

| Parameter | Type | Required | Meaning |
| - | - | - | - |
| `source` | string | Yes | Exact source ID |
| `market` | string | Yes | Normalized market ID |
| `from_` | string, date/time, or integer | Yes | Inclusive start time |
| `to` | string, date/time, or integer | Yes | Exclusive end time |
| `interval` | string | Yes | UTC-aligned duration such as `1m`, `5m`, or `1h` |
| `format` | string | No | Omit for bar dictionaries; use `"tradingview"` for TradingView-shaped output |

The default result is a list of bars with `timestamp` (UTC Unix milliseconds at bar open), `open`, `high`, `low`, `close`, `volume` (traded base volume), `trades` (trade count), and `interval`. Unlike the REST response, these bars are calculated from standardized trades. When a bar appears in an SDK event stream, its fields live under the standard event envelope's `data` object.

```python theme={null}
from datetime import datetime, timedelta, timezone
from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

with PolarisClient() as client:
    bars = client.ohlcv(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
        interval="1m",
    )

print(bars[:2])
```

### TradingView output

Pass `format="tradingview"` to receive `candles[]` and `volumes[]` instead of bar dictionaries. Each `candles[]` entry has `time` in Unix seconds and `open`, `high`, `low`, and `close`; each `volumes[]` entry has `time` in Unix seconds and `value` for bar volume.

```python theme={null}
from datetime import datetime, timedelta, timezone
from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

with PolarisClient() as client:
    tv_data = client.ohlcv(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
        interval="1m",
        format="tradingview",
    )

print(tv_data["candles"][:2], tv_data["volumes"][:2])
```

SDK historical methods can reuse standardized local files. See [SDK historical replay](/sdks/python#snapshot-first-replay) for storage and gap-handling behavior, [trade events](/schemas/trades) for the source data, and the [event envelope](/concepts/event-envelope) for nested OHLCV events.