---
title: Historical Candles
sidebar_position: 3
---

Get historical price candles for stocks or ETFs.

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

## Endpoint
```
https://api.marketdata.app/v1/stocks/candles/{resolution}/{symbol}/
```
#### Method
```
GET
```
## Request Example

<Tabs>
<TabItem value="HTTP" label="HTTP" default>

**GET** [https://api.marketdata.app/v1/stocks/candles/D/AAPL?from=2020-01-01&to=2020-12-31](https://api.marketdata.app/v1/stocks/candles/D/AAPL?from=2020-01-01&to=2020-12-31)

</TabItem>
<TabItem value="NodeJS" label="NodeJS">

```js title="app.js"
fetch(
  "https://api.marketdata.app/v1/stocks/candles/D/AAPL?from=2020-01-01&to=2020-12-31"
)
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });

```

</TabItem>
<TabItem value="Python" label="Python">

```python title="app.py"
from marketdata.client import MarketDataClient

client = MarketDataClient()
candles = client.stocks.candles("AAPL", resolution="D", from_date="2020-01-01", to_date="2020-12-31")
print(candles)
```
</TabItem>
<TabItem value="Go" label="Go">

```go title="stockCandles.go"

import (
  "fmt"

  api "github.com/MarketDataApp/sdk-go"
)

func ExampleStockCandlesRequest() {
	candles, err := StockCandles().Resolution("D").Symbol("AAPL").From("2020-01-01").To("2020-12-31").Get()
	if err != nil {
		fmt.Print(err)
		return
	}

	for _, candle := range candles {
		fmt.Println(candle)
	}
}

```
</TabItem>
</Tabs>

## Response Example

```json
{
  "s": "ok",
  "c": [217.68, 221.03, 219.89],
  "h": [222.49, 221.5, 220.94],
  "l": [217.19, 217.1402, 218.83],
  "o": [221.03, 218.55, 220],
  "t": [1569297600, 1569384000, 1569470400],
  "v": [33463820, 24018876, 20730608]
}
```

## Request Parameters

<Tabs>
<TabItem value="required" label="Required" default>

- **resolution** `string`

  The duration of each candle. *Case-insensitive*.

  **Intraday Resolutions:**
  - Minutely Resolutions: (`minutely`, `1`, `3`, `5`, `15`, `30`, `45`, ...)
  - Hourly Resolutions: (`hourly`, `H`, `1H`, `2H`, ...)

  **Daily Resolutions:**
  - Daily Resolutions: (`daily`, `D`, `1D`, `2D`, ...)
  - Weekly Resolutions: (`weekly`, `W`, `1W`, `2W`, ...)
  - Monthly Resolutions: (`monthly`, `M`, `1M`, `2M`, ...)
  - Yearly Resolutions: (`yearly`, `Y`, `1Y`, `2Y`, ...)

- **symbol** `string`

  The company's ticker symbol.

</TabItem>
<TabItem value="date" label="Dates">

All `date` parameters are optional. By default the most recent candle is returned if no date parameters are provided.

- **from** `date`

  The leftmost candle on a chart (inclusive). From and countback are mutually exclusive. If you use `countback`, `from` must be omitted. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. 

- **to** `date`

  The rightmost candle on a chart (inclusive). Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

- **countback** `number`

  Will fetch a specific number of candles before (to the left of) `to`. From and countback are mutually exclusive. If you use `from`, `countback` must be omitted.

:::note
There is no maximum date range limit on daily candles. When requesting intraday candles of any resolution, no more than 1 year of data can be requested in a single request.
:::

</TabItem>
<TabItem value="optional" label="Optional">

- **extended** `boolean`

  Include extended hours trading sessions when returning *intraday* candles. Daily resolutions _never_ return extended hours candles.

  - Daily candles default: `false`.
  - Intraday candles default: `false`.

- **adjustsplits** `boolean`

  Adjust historical data for stock splits. Market Data uses the CRSP methodology for adjustment.

  - Daily candles default: `true`.
  - Intraday candles default: `false`.

</TabItem>
</Tabs>

## Response Attributes

<Tabs>
<TabItem value="Success" label="Success" default>

- **s** `string`

  ll always be `ok` when there is data for the candles requested.

- **o** `array[number]`

  Open price.

- **h** `array[number]`

  High price.

- **l** `array[number]`

  Low price.

- **c** `array[number]`

  Close price.

- **v** `array[number]`

  Volume.

- **t** `array[number]`
  Candle time (Unix timestamp, UTC). Daily, weekly, monthly, yearly candles are returned without times.

</TabItem>
<TabItem value="NoData" label="No Data">

- **s** `string`

  Status will be `no_data` if no candles are found for the request.

- **nextTime** `number` optional

  Unix time of the next quote if there is no data in the requested period, but there is data in a subsequent period.

</TabItem>
<TabItem value="Error" label="Error">

- **s** `string`

  Status will be `error` if the request produces an error response.

- **errmsg** `string`
  An error message.

</TabItem>
</Tabs>


## Usage Information

### Data Availability

**Real-time data is not available for this endpoint under any plan or entitlement.** The type of candle data you receive depends on your user type and UTP entitlement. This may include 15-minute delayed candles or historical candles (1 day old), depending on the plan or access level.

| User Type | UTP Entitlement | Candle Type |
|-----------|----------------|-------------|
| Non-Professional | ✅ | 15-min delayed |
| Non-Professional | ❌ | Historical (1 day old) |
| Professional | Any | Historical (1 day old) |
| Unknown | Any | Historical (1 day old) |

:::info What are entitlements?
Entitlements are permissions granted by exchanges that allow access to their data. To get 15-minute delayed candles, non-professional users need to sign the [UTP agreement](/account/entitlements). [Learn more about entitlements](/account/entitlements).
:::

### Pricing

The cost of using the candle API endpoint is 1 credit per 1000 candles.

| Data Type     | Cost Basis                | Credits Required per Unit |
|--------------------|---------------------------|---------------------------|
| 15-minute Delayed Data    | Per 1000 candles         | 1 credit                  |
| Historical Data    | Per 1000 candles         | 1 credit                  |
| Real-Time Data     | Not available         | N/A                  |