---
title: "Set the Time Range"
description: "Choose the frequency and time range for a Time Series API request, understand lookback limits, and align start dates across investments."
url: "https://developer-beta.morningstar.com/time-series-api/set-the-time-range"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~U2V0IHRoZSBUaW1lIFJhbmdlIHwgVGltZSBTZXJpZXMgQVBJ,description_~Q2hvb3NlIHRoZSBmcmVxdWVuY3kgYW5kIHRpbWUgcmFuZ2UgZm9yIGEgVGltZSBTZXJpZXMgQVBJIHJlcXVlc3QsIHVuZGVyc3RhbmQgbG9va2JhY2sgbGltaXRzLCBhbmQgYWxpZ24gc3RhcnQgZGF0ZXMgYWNyb3NzIGludmVzdG1lbnRzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii90aW1lLXNlcmllcy1hcGkvc2V0LXRoZS10aW1lLXJhbmdlIg,s_861z2C8DKOO1rrze.png"
---

-   [APIs](https://developer-beta.morningstar.com/apis)
-   [API Catalog](https://developer-beta.morningstar.com/api-catalog)
-   [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp)
-   [Guides](https://developer-beta.morningstar.com/api-guides)
-   [Trial Access](https://developer-beta.morningstar.com/trial-access)

# Time Series API

Build Time Series APIs into your digital experience for quick investment and earnings summaries.

# Set the Time Range

[View Markdown](https://developer-beta.morningstar.com/time-series-api/set-the-time-range.md)[Download Markdown](https://developer-beta.morningstar.com/time-series-api/set-the-time-range.md)

A time series request needs a frequency and a time range. This page explains how to set both, the limits that apply, and how to align the start dates of several investments.

## [Frequency](#frequency)

The `frequency` parameter sets the interval between observations.

| Value     | Description |
| :-------- | :---------- |
| daily     | Default.    |
| weekly    |             |
| monthly   |             |
| quarterly |             |
| annually  |             |

For how observations are dated at each frequency, see [Core Concepts](https://developer-beta.morningstar.com/time-series-api/core-concepts#observations).

## [Choose a Time Range](#choose-a-time-range)

Define the time range with one of the following approaches.

### [Start and End Dates](#start-and-end-dates)

Pass `startDate` and `endDate` in `yyyy-MM-dd` format.

```text
GET /direct-web-services/time-series/v1/performance/daily-price/0P00000CSY
  ?startDate=2024-01-01
  &endDate=2024-12-31
```

### [Relative Time Period](#relative-time-period)

Pass `timePeriod` and `timePeriodUnit` to request a window of a given length. `timePeriod` is the number of units, and `timePeriodUnit` is `days`, `months` or `years`.

```text
GET /direct-web-services/time-series/v1/performance/daily-price/0P00000CSY
  ?timePeriod=12
  &timePeriodUnit=months
```

### [Since Inception](#since-inception)

Set `sinceInception` to `true` to request data from the start of each investment's history, or from the maximum supported lookback, to the end date.

```text
GET /direct-web-services/time-series/v1/performance/monthly-return/0P00000CSY
  ?sinceInception=true
```

`sinceInception` isn't supported for multivariate data points such as `daily-ohlcv`.

### [Which Setting Wins](#which-setting-wins)

If you combine approaches, the API applies them in this order of precedence.

| Priority | Settings                      | Effect                                                       |
| :------- | :---------------------------- | :----------------------------------------------------------- |
| 1        | sinceInception                | Overrides timePeriod, timePeriodUnit, startDate and endDate. |
| 2        | timePeriod and timePeriodUnit | Override startDate and endDate.                              |
| 3        | startDate and endDate         | Used when neither of the above is set.                       |

## [Lookback Limits](#lookback-limits)

The maximum lookback depends on the frequency and on the observation type of the data point. A request that goes further back than the limit must be split into several requests.

| Frequency | Univariate Data Points | Multivariate Data Points |
| :-------- | :--------------------- | :----------------------- |
| daily     | 12 months              | 6 months                 |
| weekly    | 60 months              | 6 months                 |
| monthly   | 120 months             | 6 months                 |
| quarterly | 600 months             | 6 months                 |
| annually  | 600 months             | 6 months                 |

The limits apply whichever approach you use to set the time range, including `sinceInception`.

## [Align Start Dates](#align-start-dates)

Investments don't all have data from the same date. The following parameters change the start of each time series. All three default to `false`.

| Parameter                 | Effect                                                                           |
| :------------------------ | :------------------------------------------------------------------------------- |
| applyEarliestCommonDate   | Moves the start date of every time series to the latest inception date among the requested investments, so all series start on the same date. |
| applyRestructureDate      | Considers the Morningstar or custom restructure date when determining the start of the performance period. Applies only when applyEarliestCommonDate is true. |
| applyTrackRecordExtension | Extends an investment's performance by copying the historical performance of another qualified, older investment. |

The following request aligns three investments to a common start date.

```text
GET /direct-web-services/time-series/v1/performance/monthly-return/0P00000CSY,0P00002D6U,0P00001XK7
  ?startDate=2010-01-01
  &endDate=2024-12-31
  &frequency=monthly
  &applyEarliestCommonDate=true
```

Aligned start dates are useful when you want to compare investments over the same period.