Skip to main content

Historical Candle Data V3​

Compared to the standard Historical Candle Data API, API V3 allows users to retrieve data in custom time intervals for each unit (minutes, hours, days, weeks, and months), enabling more granular data control and improved flexibility for analysis. The response structure maintains consistency with the standard Historical Candle Data API format, facilitating seamless integration with existing applications and systems.

The API is designed to handle large volumes of data efficiently, ensuring quick response times even for extensive historical queries.

This API is particularly useful for traders and analysts who need to analyze historical price movements and trends in the financial markets.

The API offers OHLC (Open, High, Low, Close) data for instruments across multiple timeframes, with different historical availability and retrieval constraints based on the selected unit and interval as per the below table:

UnitInterval OptionsHistorical AvailabilityMax retrieval record limit
minutes1, 2, ... 300Available from January, 20221 month - Applicable for intervals ranging from 1 to 15 minutes.

1 quarter - Used for intervals greater than 15 minutes, up to the specified to_date.
hours1, 2, ... 5Available from January, 20221 quarter leading up to the to_date.
days1Available from January, 20001 decade leading up to the to_date.
weeks1Available from January, 2000No limit.
months1Available from January, 2000No limit.
NOTE
  • Use the Intraday Candle Data API V3 to retrieve data specific to the current trading day with the wide range of units and intervals.
  • It's important to note that if the retrieval record limit is exceeded, then the API will throw an error indicating that the request is invalid.
  • This V3 API provides additional custom interval options that are not available in the standard Historical Candle Data API.

Header Parameters​

NameRequiredTypeDescription
AccepttruestringDefines the content format the client expects, which should be set to application/json.

Path Parameters​

NameRequiredTypeDescription
instrument_keytruestringThe unique identifier for the financial instrument for which historical data is being queried. For the regex pattern applicable to this field, see the Field Pattern Appendix.
unittruestringSpecifies the unit for the candles.
Possible values: minutes, hours, days, weeks, months.
intervaltruestringSpecifies the interval for the candles.
Possible values:
1, 2, 3, ..., 300 for minutes.
1, 2, ..., 5 for hours.
1 for days, weeks, and months.
to_datetruestringThe ending date (inclusive) for the historical data range. Format: 'YYYY-MM-DD'.
from_datefalsestringThe starting date for the historical data range. Format: 'YYYY-MM-DD'.
Responses

Response Body​

{
  "status": "success",
  "data": {
    "candles": [
      [
        "2025-01-01T00:00:00+05:30",
        53.1,
        53.95,
        51.6,
        52.05,
        235519861,
        0
      ],
      [
        "2025-02-01T00:00:00+05:30",
        50.35,
        56.85,
        49.35,
        52.8,
        1004998611,
        0
      ]
    ]
  }
}
NameTypeDescription
statusstringA string indicating the outcome of the request. Typically success for successful operations.
dataobjectContains OHLC values for all instruments across various timeframes.
data.candlesarray[]Array of candle data, each presented as an array with sequential elements representing trading activity.
data.candle[0]numberTimestamp: Indicating the start time of the candle's timeframe.
data.candle[1]numberOpen: The opening price of the asset for the given timeframe.
data.candle[2]numberHigh: The highest price at which the asset traded during the timeframe.
data.candle[3]numberLow: The lowest price at which the asset traded during the timeframe.
data.candle[4]numberClose: The closing price of the asset for the given timeframe.
data.candle[5]numberVolume: The total amount of the asset that was traded during the timeframe.
data.candle[6]numberOpen Interest: The total number of outstanding derivative contracts, such as options or futures.

Examples​

A comprehensive set of examples is provided to illustrate various use cases and implementation scenarios for this API. To view detailed examples and access sample code, please refer to: API Examples.

GET /historical-candle/:instrument_key/:unit/:interval/:to_date/:from_date

Request

https://api.upstox.com/v3
Authorization
Bearer
instrument_key — path required
unit — path required
interval — path required
to_date — path required
from_date — path
curl / cURL
curl -L -X GET 'https://api.upstox.com/v3/historical-candle/:instrument_key/:unit/:interval/:to_date/:from_date' \
-H 'Accept: application/json'