> ## Documentation Index > Fetch the complete documentation index at: https://developers.takeprofit.com/llms.txt > Use this file to discover all available pages before exploring further. # List Candles > The `ListCandles` method retrieves historical candlestick data for a given security, time frame, and range. This documentation provides details on how to use the `ListCandles` endpoint, including request and response formats, and includes JSON schemas for the request and response. ### Request Body - `security_id` (object, required): Identifier of the security. - One of: - `guid` (string): Global Unique Identifier of the security. - `ticker_code` (object): - `ticker` (string): Ticker symbol. - `exchange_code` (string): Exchange code. - `time_frame` (object, required): Time frame for the candles. - `time_unit` (string, required): Unit of time. Possible values: `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`. - `count` (integer): Number of `time_unit`s per candle (e.g., 1 for daily candles). - `range` (object, required): Range of the historical data. - One of: - `first_bound_time` (string): The starting time (ISO 8601 format). - `second_bound_time` (string): The ending time (ISO 8601 format). - `duration` (string): Duration of the range (e.g., `"PT5H"` for 5 hours). - `count` (integer): Number of candles to retrieve. Negative for past data relative to `first_bound_time`. ### Response - `candles` (array): An array of candle objects. - Each candle object contains: - `time` (string): The start time of the candle in ISO 8601 format. - `open` (object): Open price. - `value` (string): Numeric value as a string. - `scale` (string): Scale factor (divisor). - `high` (object): High price. - `low` (object): Low price. - `close` (object): Close price. - `volume` (object): Volume. - `session_type` (integer): Session type (e.g., 0 for MAINSESSION). --- ## JSON Schemas ### Request Schema ``` json { "type": "object", "properties": { "security_id": { "type": "object", "oneOf": [ { "properties": { "guid": { "type": "string" } }, "required": ["guid"] }, { "properties": { "ticker_code": { "type": "object", "properties": { "ticker": { "type": "string" }, "exchange_code": { "type": "string" } }, "required": ["ticker", "exchange_code"] } }, "required": ["ticker_code"] } ] }, "time_frame": { "type": "object", "properties": { "time_unit": { "type": "string", "enum": ["MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"] }, "count": { "type": "integer", "minimum": 1 } }, "required": ["time_unit"] }, "range": { "type": "object", "oneOf": [ { "properties": { "first_bound_time": { "type": "string", "format": "date-time" }, "second_bound_time": { "type": "string", "format": "date-time" } }, "required": ["first_bound_time", "second_bound_time"] }, { "properties": { "first_bound_time": { "type": "string", "format": "date-time" }, "duration": { "type": "string" } }, "required": ["first_bound_time", "duration"] }, { "properties": { "first_bound_time": { "type": "string", "format": "date-time" }, "count": { "type": "integer" } }, "required": ["first_bound_time", "count"] } ] }, "properties": { "type": "array", "items": { "type": "string", "enum": ["OPEN", "HIGH", "LOW", "CLOSE", "VALUE", "VOLUME", "SESSION_TYPE"] } }, "session_types": { "type": "array", "items": { "type": "string", "enum": ["MAINSESSION", "PRE_MARKET", "POST_MARKET"] } } }, "required": ["security_id", "time_frame", "range"] } ``` ### Response Schema ``` json { "type": "object", "properties": { "candles": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "open": { "$ref": "#/definitions/Decimal" }, "high": { "$ref": "#/definitions/Decimal" }, "low": { "$ref": "#/definitions/Decimal" }, "close": { "$ref": "#/definitions/Decimal" }, "volume": { "$ref": "#/definitions/Decimal" }, "session_type": { "type": "integer", "enum": [0, 1, 2] } }, "required": ["time"] } } }, "definitions": { "Decimal": { "type": "object", "properties": { "value": { "type": "string" }, "scale": { "type": "string" } }, "required": ["value", "scale"] } } } ``` --- ## Usage Recommendations - **Authorization**: Always use a valid `access_token` in the `accesstoken` header. - **Error Handling**: Check the `status` field in the response to determine the success of the operation. - **Time Zones**: All times are in UTC. Ensure your application handles time zones appropriately. - **Data Interpretation**: - **Decimal Fields**: To calculate the real value of decimal fields, use `real_value = value / scale`. For example, if `value` is `"21210"` and `scale` is `"100"`, the real value is `21210 / 100 = 212.10`. --- ## Frequently Asked Questions ### How do I interpret the `Decimal` fields? The `Decimal` fields use a `value` and `scale` to represent decimal numbers precisely. Compute the real value as `value / scale`. ### What is the `session_type` field? The `session_type` indicates the trading session: - `0`: MAINSESSION - `1`: PRE_MARKET - `2`: POST_MARKET ### Can I request candles for a custom time frame? Yes, you can specify the `time_frame` with different `time_unit` and `count` values to create custom time frames, such as 5-minute or 15-minute candles. --- ## Additional Resources - [Auth API Documentation](#) - [ISO 8601 Date Format](https://en.wikipedia.org/wiki/ISO_8601) ## OpenAPI ````yaml post /takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles openapi: 3.0.0 info: title: TakeProfit Partner API description: TakeProfit Partner API documentation version: 0.1-beta servers: - url: https://api.dev.tpinf.in description: Development environment - url: https://api.takeprofit.com description: '''Production environment''' security: [] tags: - name: Partner API - name: Credentials description: >- The Credentials API allows partners to authenticate and obtain access tokens required for accessing other secured endpoints. This documentation provides details on how to use the authentication endpoints, including request and response formats. ## Overview The Authentication API provides two primary endpoints: 1. **Create Token**: Authenticates a partner using their API key and returns an access token and a refresh token. 2. **Refresh Token**: Generates a new access token using a valid refresh token. - name: Link description: >- The Link API allows partners to manage the linkage between their own securities and the securities provided by TakeProfit. This includes creating, retrieving, and deleting links between securities. - name: Reference API description: Set of APIs to get reference info such as exchanges, securities. - name: Marketdata API description: Set of APIs to get marketdata such as historical candles - name: Widgets description: |- Describe how to use TakeProfit Backend API from Widgets. Each request to API must has 'accesstoken' header with valid JWT-token. Describe here how to obtain JWT for widget. paths: /takeprofit.marketdata.external.candle.v1.CandleHistoryApi.ListCandles: post: tags: - Marketdata API summary: List Candles description: >- The `ListCandles` method retrieves historical candlestick data for a given security, time frame, and range. This documentation provides details on how to use the `ListCandles` endpoint, including request and response formats, and includes JSON schemas for the request and response. ### Request Body - `security_id` (object, required): Identifier of the security. - One of: - `guid` (string): Global Unique Identifier of the security. - `ticker_code` (object): - `ticker` (string): Ticker symbol. - `exchange_code` (string): Exchange code. - `time_frame` (object, required): Time frame for the candles. - `time_unit` (string, required): Unit of time. Possible values: `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`. - `count` (integer): Number of `time_unit`s per candle (e.g., 1 for daily candles). - `range` (object, required): Range of the historical data. - One of: - `first_bound_time` (string): The starting time (ISO 8601 format). - `second_bound_time` (string): The ending time (ISO 8601 format). - `duration` (string): Duration of the range (e.g., `"PT5H"` for 5 hours). - `count` (integer): Number of candles to retrieve. Negative for past data relative to `first_bound_time`. ### Response - `candles` (array): An array of candle objects. - Each candle object contains: - `time` (string): The start time of the candle in ISO 8601 format. - `open` (object): Open price. - `value` (string): Numeric value as a string. - `scale` (string): Scale factor (divisor). - `high` (object): High price. - `low` (object): Low price. - `close` (object): Close price. - `volume` (object): Volume. - `session_type` (integer): Session type (e.g., 0 for MAINSESSION). --- ## JSON Schemas ### Request Schema ``` json { "type": "object", "properties": { "security_id": { "type": "object", "oneOf": [ { "properties": { "guid": { "type": "string" } }, "required": ["guid"] }, { "properties": { "ticker_code": { "type": "object", "properties": { "ticker": { "type": "string" }, "exchange_code": { "type": "string" } }, "required": ["ticker", "exchange_code"] } }, "required": ["ticker_code"] } ] }, "time_frame": { "type": "object", "properties": { "time_unit": { "type": "string", "enum": ["MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"] }, "count": { "type": "integer", "minimum": 1 } }, "required": ["time_unit"] }, "range": { "type": "object", "oneOf": [ { "properties": { "first_bound_time": { "type": "string", "format": "date-time" }, "second_bound_time": { "type": "string", "format": "date-time" } }, "required": ["first_bound_time", "second_bound_time"] }, { "properties": { "first_bound_time": { "type": "string", "format": "date-time" }, "duration": { "type": "string" } }, "required": ["first_bound_time", "duration"] }, { "properties": { "first_bound_time": { "type": "string", "format": "date-time" }, "count": { "type": "integer" } }, "required": ["first_bound_time", "count"] } ] }, "properties": { "type": "array", "items": { "type": "string", "enum": ["OPEN", "HIGH", "LOW", "CLOSE", "VALUE", "VOLUME", "SESSION_TYPE"] } }, "session_types": { "type": "array", "items": { "type": "string", "enum": ["MAINSESSION", "PRE_MARKET", "POST_MARKET"] } } }, "required": ["security_id", "time_frame", "range"] } ``` ### Response Schema ``` json { "type": "object", "properties": { "candles": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "open": { "$ref": "#/definitions/Decimal" }, "high": { "$ref": "#/definitions/Decimal" }, "low": { "$ref": "#/definitions/Decimal" }, "close": { "$ref": "#/definitions/Decimal" }, "volume": { "$ref": "#/definitions/Decimal" }, "session_type": { "type": "integer", "enum": [0, 1, 2] } }, "required": ["time"] } } }, "definitions": { "Decimal": { "type": "object", "properties": { "value": { "type": "string" }, "scale": { "type": "string" } }, "required": ["value", "scale"] } } } ``` --- ## Usage Recommendations - **Authorization**: Always use a valid `access_token` in the `accesstoken` header. - **Error Handling**: Check the `status` field in the response to determine the success of the operation. - **Time Zones**: All times are in UTC. Ensure your application handles time zones appropriately. - **Data Interpretation**: - **Decimal Fields**: To calculate the real value of decimal fields, use `real_value = value / scale`. For example, if `value` is `"21210"` and `scale` is `"100"`, the real value is `21210 / 100 = 212.10`. --- ## Frequently Asked Questions ### How do I interpret the `Decimal` fields? The `Decimal` fields use a `value` and `scale` to represent decimal numbers precisely. Compute the real value as `value / scale`. ### What is the `session_type` field? The `session_type` indicates the trading session: - `0`: MAINSESSION - `1`: PRE_MARKET - `2`: POST_MARKET ### Can I request candles for a custom time frame? Yes, you can specify the `time_frame` with different `time_unit` and `count` values to create custom time frames, such as 5-minute or 15-minute candles. --- ## Additional Resources - [Auth API Documentation](#) - [ISO 8601 Date Format](https://en.wikipedia.org/wiki/ISO_8601) parameters: - name: accesstoken in: header schema: type: string description: JWT access token example: YOUR_ACCESS_TOKEN_HERE requestBody: content: application/json: schema: type: object example: security_id: guid: 6ef11658-5a1c-4baf-9387-d977dcca6129 time_frame: time_unit: DAY count: 1 range: count: -5 first_bound_time: '2024-08-16T00:00:00Z' responses: '200': description: OK headers: content-type: schema: type: string example: application/json grpc-accept-encoding: schema: type: string example: identity, deflate, gzip x-envoy-upstream-service-time: schema: type: integer example: '10' access-control-expose-headers: schema: type: string example: grpc-status, grpc-message, x-grpc-details, my-test my-little-header: schema: type: string example: my-test access-control-allow-origin: schema: type: string example: '*' grpc-status: schema: type: integer example: '0' content-length: schema: type: integer example: '1860' date: schema: type: string example: Wed, 06 Nov 2024 06:57:20 GMT server: schema: type: string example: envoy content: application/json: schema: type: object example: candles: - time: '2024-08-09T00:00:00Z' open: value: '21210' scale: '100' high: value: '21678' scale: '100' low: value: '21197' scale: '100' close: value: '21624' scale: '100' volume: value: '42201600' scale: '1' session_type: 0 - time: '2024-08-12T00:00:00Z' open: value: '21607' scale: '100' high: value: '21951' scale: '100' low: value: '21560' scale: '100' close: value: '21753' scale: '100' volume: value: '38028100' scale: '1' session_type: 0 - time: '2024-08-13T00:00:00Z' open: value: '21901' scale: '100' high: value: '22189' scale: '100' low: value: '21901' scale: '100' close: value: '22127' scale: '100' volume: value: '44155300' scale: '1' session_type: 0 - time: '2024-08-14T00:00:00Z' open: value: '22057' scale: '100' high: value: '22303' scale: '100' low: value: '21970' scale: '100' close: value: '22172' scale: '100' volume: value: '41960600' scale: '1' session_type: 0 - time: '2024-08-15T00:00:00Z' open: value: '22460' scale: '100' high: value: '22535' scale: '100' low: value: '22276' scale: '100' close: value: '22472' scale: '100' volume: value: '46414000' scale: '1' session_type: 0 ````