> ## 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.

# Historical options ticker

> Query paginated option-ticker observations for an underlying or one contract.

Use `GET /historical/options-ticker` to read partial venue-published option observations in global collector-time order. Each flat REST row identifies a normalized underlying in `market` and an exact venue-native option contract in `instrument`. The [Option tickers schema page](/schemas/option-tickers) describes the SDK and snapshot event envelope.

Omit `instrument` to query the whole underlying chain, or provide it to select one contract. Decimal prices, sizes, implied volatility, and Greeks are returned as **strings** to preserve their lossless representation. A null field was not supplied in that observation; do not carry earlier values forward as if the API returned a complete ticker state.

## Access and time range

Omit both `start` and `end` to query the latest ten minutes without authentication. Supply either bound to query a chosen interval with a Polaris API key in `Authorization: Bearer YOUR_API_KEY`. `start` and `end` are **inclusive collector timestamps in Unix milliseconds**. With only `start`, the query runs through now; with only `end`, it covers the preceding ten minutes.

## Query parameters

<ParamField query="source" type="string">
  Exact source ID. Omit to query across sources.
</ParamField>

<ParamField query="market" type="string">
  Exact normalized underlying market, such as `BTC`. Omit to query across markets.
</ParamField>

<ParamField query="instrument" type="string">
  Exact venue-native option contract. Omit to query the whole underlying chain.
</ParamField>

<ParamField query="start" type="integer">
  Inclusive collector time in Unix milliseconds. Requires a Polaris API key.
</ParamField>

<ParamField query="end" type="integer">
  Inclusive collector time in Unix milliseconds. Requires a Polaris API key.
</ParamField>

<ParamField query="limit" type="integer" default={200}>
  Page size from `1` to `1000`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque `next_cursor` from the previous page of the same query.
</ParamField>

Use [Catalog](/reference/catalog) to find exact source and market IDs.

## Request and response

```bash theme={null}
curl "https://api.polaris.supply/historical/options-ticker?source=deribit&market=BTC&limit=2"
```

Example response shape:

```json theme={null}
{
  "items": [
    {
      "event_id": "option-123",
      "source": "deribit",
      "market": "BTC",
      "instrument": "BTC-29MAR24-50000-C",
      "collector_timestamp": 1711612800000,
      "exchange_timestamp": null,
      "source_capture_id": "capture-123",
      "schema_version": 2,
      "option_type": "call",
      "strike": "50000",
      "expiry_timestamp": 1711699200000,
      "bid_price": "0.12",
      "ask_price": "0.13",
      "mark_iv": "0.58",
      "delta": "0.64",
      "open_interest": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

`items` contains flat rows ordered by `collector_timestamp` across matching sources. `event_id`, `source`, `market`, `instrument`, `collector_timestamp`, `source_capture_id`, and `schema_version` are required. The other fields can be null:

| Fields                                                                                                             | Type                   | Meaning                                                    |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------------------------------- |
| `exchange_timestamp`, `expiry_timestamp`                                                                           | integer or null        | Venue event time and contract expiry, in Unix milliseconds |
| `underlying`, `option_type`, `premium_currency`, `quantity_unit`                                                   | string or null         | Contract identity and units                                |
| `strike`, `bid_price`, `ask_price`, `last_price`, `mark_price`, `index_price`, `underlying_price`, `forward_price` | decimal string or null | Strike and published prices                                |
| `bid_size`, `ask_size`, `open_interest`, `volume_24h`, `turnover_24h`                                              | decimal string or null | Published size and activity                                |
| `bid_iv`, `ask_iv`, `mark_iv`, `delta`, `gamma`, `vega`, `theta`, `rho`                                            | decimal string or null | Implied volatility and Greeks                              |

## Pagination and errors

When `has_more` is `true`, send `next_cursor` as `cursor` while keeping the other query parameters unchanged. Stop when `has_more` is `false`; `next_cursor` is then null or absent.

The API documents `400` for an invalid request, `401` when authentication is needed, `422` when query work exceeds its limit, `429` when the request quota is exceeded, and `503` when the service is unavailable. Narrow the requested time range after a `422`; respect `Retry-After` after a `429`. Errors have an `error` object with `code`, `message`, and `resolution`.

## Related documentation

* [Option tickers schema](/schemas/option-tickers) for SDK and snapshot event fields
* [Python SDK](/sdks/python), [TypeScript SDK](/sdks/typescript), and [Rust SDK](/sdks/rust) for client methods
* [Snapshots](/reference/snapshots) for bulk historical files