> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stratalerts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Candles

> Fetch open, high, low, close, and volume bars for a symbol across 10 intervals from 1-minute intraday to yearly. Filter by date range or limit bar count.

## Retrieve OHLCV bars for any timeframe

The candles endpoint returns historical OHLCV (open, high, low, close, volume) bars for a single symbol at a requested interval. You can retrieve everything from 1-minute intraday data up to yearly bars, and optionally narrow the result to a specific date range. When the market is open, the most recent bar may still be forming — the `partial_bar_included` flag tells you whether that is the case.

**`GET https://app.stratalerts.com/api/market/v1/candles/{symbol}`**

<Note>
  Requires scope: `candles:read`
</Note>

## Path parameters

<ParamField path="symbol" type="string" required>
  The ticker symbol (e.g., `AAPL`, `ES1!`). Case-insensitive — normalized to uppercase.
</ParamField>

## Query parameters

<ParamField query="interval" default="1d" type="string">
  The bar interval. Must be one of the following values:

  | Value | Description |
  | ----- | ----------- |
  | `1m`  | 1-minute    |
  | `15m` | 15-minute   |
  | `30m` | 30-minute   |
  | `60m` | 60-minute   |
  | `4h`  | 4-hour      |
  | `1d`  | Daily       |
  | `1w`  | Weekly      |
  | `1mo` | Monthly     |
  | `1q`  | Quarterly   |
  | `1y`  | Yearly      |

  An unrecognized interval value returns a `404` response.
</ParamField>

<ParamField query="start" type="string">
  Start of the date range. Accepts an ISO 8601 datetime string (`2026-01-15T09:30:00Z`) or a plain date string (`2026-01-15`). Plain dates are interpreted as midnight UTC. Bars with a `time` value before this timestamp are excluded.
</ParamField>

<ParamField query="end" type="string">
  End of the date range. Same format as `start`. Bars with a `time` value after this timestamp are excluded.
</ParamField>

<ParamField query="limit" default="500" type="number">
  Maximum number of bars to return. Clamped to the range `1–5000`. When a `start`/`end` range is also provided, the limit is applied after filtering — returning the most recent `limit` bars within that range.
</ParamField>

## Response fields

<ResponseField name="symbol" type="string" required>
  The requested ticker symbol, uppercased.
</ResponseField>

<ResponseField name="interval" type="string" required>
  The normalized interval string you requested (e.g., `1d`).
</ResponseField>

<ResponseField name="bars" type="object[]" required>
  Array of OHLCV bar objects ordered chronologically (oldest first).

  <Expandable title="bar object">
    <ResponseField name="time" type="number" required>
      Bar open timestamp as a Unix timestamp (seconds since epoch, UTC).
    </ResponseField>

    <ResponseField name="open" type="number" required>
      Opening price for the bar period.
    </ResponseField>

    <ResponseField name="high" type="number" required>
      Highest price reached during the bar period.
    </ResponseField>

    <ResponseField name="low" type="number" required>
      Lowest price reached during the bar period.
    </ResponseField>

    <ResponseField name="close" type="number" required>
      Closing price for the bar period.
    </ResponseField>

    <ResponseField name="volume" type="number" required>
      Total volume traded during the bar period.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="partial_bar_included" type="boolean" required>
  `true` when the final bar in the array is still forming (i.e., the current period has not yet closed). Always `false` for the `1m` interval and for any request made outside market hours.
</ResponseField>

<Warning>
  When `partial_bar_included` is `true`, the last bar's `high`, `low`, `close`, and `volume` values will change as the period progresses. Do not treat a partial bar as a confirmed candle for setup or signal calculations.
</Warning>

## Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.stratalerts.com/api/market/v1/candles/AAPL" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "interval=1d" \
    --data-urlencode "limit=10"
  ```

  ```python python theme={null}
  import requests

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/candles/AAPL",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"interval": "1d", "limit": 10},
  )
  resp.raise_for_status()
  data = resp.json()
  print("partial bar included:", data["partial_bar_included"])
  for bar in data["bars"]:
      print(bar["time"], bar["open"], bar["close"])
  ```

  ```javascript javascript theme={null}
  const resp = await fetch(
    "https://app.stratalerts.com/api/market/v1/candles/AAPL?interval=1d&limit=10",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();
  console.log("partial bar included:", data.partialBarIncluded);
  data.bars.forEach(({ time, open, close }) => console.log(time, open, close));
  ```
</CodeGroup>

### Fetching a date range

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.stratalerts.com/api/market/v1/candles/SPY" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "interval=1w" \
    --data-urlencode "start=2026-01-01" \
    --data-urlencode "end=2026-03-31"
  ```

  ```python python theme={null}
  import requests

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/candles/SPY",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"interval": "1w", "start": "2026-01-01", "end": "2026-03-31"},
  )
  resp.raise_for_status()
  data = resp.json()
  print(f"{len(data['bars'])} weekly bars returned")
  ```

  ```javascript javascript theme={null}
  const params = new URLSearchParams({
    interval: "1w",
    start: "2026-01-01",
    end: "2026-03-31",
  });
  const resp = await fetch(
    `https://app.stratalerts.com/api/market/v1/candles/SPY?${params}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();
  console.log(`${data.bars.length} weekly bars returned`);
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "symbol": "AAPL",
  "interval": "1d",
  "bars": [
    {
      "time": 1744243200,
      "open": 210.50,
      "high": 215.80,
      "low": 209.30,
      "close": 214.32,
      "volume": 62400000
    },
    {
      "time": 1744329600,
      "open": 214.50,
      "high": 217.10,
      "low": 213.20,
      "close": 216.75,
      "volume": 55100000
    }
  ],
  "partial_bar_included": false
}
```

## Error codes

| HTTP status | Error code             | Meaning                                                          |
| ----------- | ---------------------- | ---------------------------------------------------------------- |
| 401         | `missing_api_key`      | No API key was provided or the key format is invalid.            |
| 403         | `inactive_entitlement` | Your account does not have an active API entitlement.            |
| 403         | `missing_scope`        | Your API key does not have the `candles:read` scope.             |
| 404         | `unknown_symbol`       | The symbol path parameter was not found in the tracked universe. |

An unrecognized `interval` value also returns a `404` with no error body.

Error responses use the following shape:

```json theme={null}
{
  "error": {
    "code": "unknown_symbol",
    "message": "unknown symbol"
  }
}
```