> ## Documentation Index > Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Candlesticks > Retrieve historical OHLCV candlestick data for a Polymarket token over a defined time interval. **Platform:** Polymarket\ **Endpoint:** `POST /v2/semantic/retrieve/parameterized`\ **Authentication:** Bearer token ## Query parameters All requests use `agent_id` `568` (Candlesticks). Set filters inside `params` in the playground — all values must be strings. | Parameter | Type | Description | | - | - | - | | `token_id` | String | Token ID of the market outcome. Get this from [Polymarket Markets](/docs/market-data/polymarket-markets) (`side_a_token_id` / `side_b_token_id`). | | `interval` | String | Candle interval: `1m`, `5m`, `15m`, `1h`, `4h`, or `1d`. | | `start_time` | String | Unix timestamp in seconds for the range start (for example, `"1769910300"`). | | `end_time` | String | Unix timestamp in seconds for the range end (for example, `"1770034843377"`). | ## Example Request ```bash cURL theme={null} curl --request POST \ --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": 568, "params": { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "interval": "1h", "start_time": "1769910300", "end_time": "1770034843377" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }' ``` ```python Python theme={null} import requests response = requests.post( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "agent_id": 568, "params": { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "interval": "1h", "start_time": "1769910300", "end_time": "1770034843377" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } } ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", { method: "POST", headers: { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "agent_id": 568, "params": { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "interval": "1h", "start_time": "1769910300", "end_time": "1770034843377" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }) }); const data = await response.json(); ``` ## Example Response ```json theme={null} { "timestamp": "", "params": { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "interval": "1h", "start_time": "1769910300", "end_time": "1770034843377" }, "data": { "results": [ { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "timestamp": "2026-04-10T18:00:00Z", "open": "0.5600", "high": "0.5850", "low": "0.5520", "close": "0.5800", "volume": "42310.55" }, { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "timestamp": "2026-04-10T17:00:00Z", "open": "0.5450", "high": "0.5620", "low": "0.5400", "close": "0.5600", "volume": "31880.20" } ] } } ``` ## Response fields | Field | Type | Description | | - | - | - | | `token_id` | String | Token ID | | `timestamp` | String (ISO 8601) | Candle start time | | `open` | String (Decimal) | Opening price | | `high` | String (Decimal) | Highest price | | `low` | String (Decimal) | Lowest price | | `close` | String (Decimal) | Closing price | | `volume` | String (Decimal) | Volume during candle (USD) | ## Notes > [!TIP] > > Use shorter intervals (e.g., `1m`, `5m`) intervals for intraday / pre-game analysis > [!TIP] > > Always match the interval with an appropriate `start_time` and `end_time` range. Requesting more data than the max range for a given interval will produce empty or incomplete results. > [!TIP] > > Use `offset` in the pagination object when retrieving large datasets to iterate through results efficiently. ## OpenAPI ````yaml /api-reference/polymarket-candlesticks.openapi.json POST /api/v2/semantic/retrieve/parameterized openapi: 3.1.0 info: title: Falcon API — Candlesticks version: 1.0.0 servers: - url: https://narrative.agent.heisenberg.so description: Production security: - bearerAuth: [] paths: /api/v2/semantic/retrieve/parameterized: post: tags: - Polymarket summary: Candlesticks description: >- Retrieve historical OHLCV candlestick data for a Polymarket token over a defined time interval. operationId: polymarketCandlesticks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PolymarketCandlesticksRequest' examples: default: summary: 1h candles for a token value: agent_id: 568 params: token_id: >- 85953619064670985626771564660881103494957821937504170459975285010511861618293 interval: 1h start_time: '1769910300' end_time: '1770034843377' pagination: limit: 10 offset: 0 formatter_config: format_type: raw responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PolymarketCandlesticksResponse' '400': description: Bad request — check params '401': description: Unauthorized — check your Bearer token x-codeSamples: - lang: curl label: cURL source: |- curl --request POST \ --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": 568, "params": { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "interval": "1h", "start_time": "1769910300", "end_time": "1770034843377" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }' - lang: python label: Python source: |- import requests response = requests.post( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "agent_id": 568, "params": { "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "interval": "1h", "start_time": "1769910300", "end_time": "1770034843377", }, "pagination": {"limit": 10, "offset": 0}, "formatter_config": {"format_type": "raw"}, }, ) print(response.json()) - lang: javascript label: JavaScript source: |- const response = await fetch( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", { method: "POST", headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ agent_id: 568, params: { token_id: "85953619064670985626771564660881103494957821937504170459975285010511861618293", interval: "1h", start_time: "1769910300", end_time: "1770034843377", }, pagination: { limit: 10, offset: 0 }, formatter_config: { format_type: "raw" }, }), } ); const data = await response.json(); components: schemas: PolymarketCandlesticksRequest: type: object required: - params properties: agent_id: type: integer enum: - 568 default: 568 x-default: 568 description: Candlesticks agent ID. params: $ref: '#/components/schemas/PolymarketCandlesticksParams' pagination: $ref: '#/components/schemas/PolymarketCandlesticksPagination' formatter_config: $ref: '#/components/schemas/PolymarketCandlesticksFormatterConfig' PolymarketCandlesticksResponse: type: object readOnly: true properties: timestamp: type: string readOnly: true params: $ref: '#/components/schemas/PolymarketCandlesticksResponseParams' pagination: type: object readOnly: true properties: limit: type: integer readOnly: true offset: type: integer readOnly: true has_more: type: boolean readOnly: true data: type: object readOnly: true properties: results: type: array readOnly: true items: $ref: '#/components/schemas/PolymarketCandlestickRecord' request_id: type: string readOnly: true PolymarketCandlesticksParams: type: object description: Filter parameters. All values must be strings. additionalProperties: false required: - token_id - interval properties: token_id: type: string description: >- Token ID of the market outcome. Find this on the Polymarket Markets endpoint (`side_a_token_id` / `side_b_token_id`). interval: type: string enum: - 1m - 5m - 15m - 1h - 4h - 1d description: Candle interval (for example, "1h" for hourly candles). start_time: type: string description: >- Unix timestamp in seconds for the range start, as a string (for example, "1769910300"). end_time: type: string description: >- Unix timestamp in seconds for the range end, as a string (for example, "1770034843377"). PolymarketCandlesticksPagination: type: object properties: limit: type: integer minimum: 1 maximum: 200 default: 10 description: Maximum number of records returned per request. offset: type: integer minimum: 0 default: 0 description: Number of records to skip before returning results. PolymarketCandlesticksFormatterConfig: type: object properties: format_type: type: string enum: - raw default: raw description: Output format. Use "raw" for structured JSON. PolymarketCandlesticksResponseParams: type: object readOnly: true properties: token_id: type: string readOnly: true interval: type: string readOnly: true start_time: type: string readOnly: true end_time: type: string readOnly: true PolymarketCandlestickRecord: type: object readOnly: true properties: token_id: type: string readOnly: true description: Token ID timestamp: type: string readOnly: true description: Candle start time (ISO 8601) open: type: string readOnly: true description: Opening price high: type: string readOnly: true description: Highest price low: type: string readOnly: true description: Lowest price close: type: string readOnly: true description: Closing price volume: type: string readOnly: true description: Volume during candle (USD) securitySchemes: bearerAuth: type: http scheme: bearer description: Your Falcon API key from the dashboard ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.