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

> Query paginated, normalized trade rows directly from the historical REST API.

Use `GET /historical/trades` to read source-independent executions in global collector-time order. The response contains flat trade rows, rather than the `type` and `data` event envelope shown on the [Trades schema page](/schemas/trades).

## 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 routing market. Omit to query across markets.
</ParamField>

<ParamField query="instrument" type="string">
  Exact venue-native instrument, when you need to narrow the market further.
</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/trades?source=hyperliquid&market=BTC&limit=2"
```

Example response shape:

```json theme={null}
{
  "items": [
    {
      "event_id": "trade-123",
      "source": "hyperliquid",
      "market": "BTC",
      "instrument": null,
      "collector_timestamp": 1727200000000,
      "exchange_timestamp": 1727199999998,
      "source_capture_id": "capture-123",
      "schema_version": 2,
      "price": 63450.5,
      "quantity": 0.2,
      "side": "buy",
      "order_id": "order-123",
      "maker": null,
      "taker": null,
      "liquidation": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

`items` contains flat rows ordered by `collector_timestamp` across matching sources. `event_id`, `source`, `market`, `collector_timestamp`, `source_capture_id`, `schema_version`, `price`, and `quantity` are required in each row. `price` and `quantity` are numbers. `instrument`, `exchange_timestamp`, `side`, `order_id`, `maker`, `taker`, and `liquidation` can be null.

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

* [Trades schema](/schemas/trades) 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