---
title: "Request Time Series Data"
description: "Build a Time Series API request: the endpoint pattern, headers, request steps, output currency, limits and the responses you can expect."
url: "https://developer-beta.morningstar.com/time-series-api/request-time-series-data"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~UmVxdWVzdCBUaW1lIFNlcmllcyBEYXRhIHwgVGltZSBTZXJpZXMgQVBJ,description_~QnVpbGQgYSBUaW1lIFNlcmllcyBBUEkgcmVxdWVzdDogdGhlIGVuZHBvaW50IHBhdHRlcm4sIGhlYWRlcnMsIHJlcXVlc3Qgc3RlcHMsIG91dHB1dCBjdXJyZW5jeSwgbGltaXRzIGFuZCB0aGUgcmVzcG9uc2VzIHlvdSBjYW4gZXhwZWN0Lg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii90aW1lLXNlcmllcy1hcGkvcmVxdWVzdC10aW1lLXNlcmllcy1kYXRhIg,s_k7bWdS216mZSOq6P.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.

# Request Time Series Data

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

To retrieve time series data, you call the endpoint for a data point and pass the investments and settings you want. This page gives an overview of how a request is built. The pages in this section cover each part of the request in detail.

## [Endpoint Pattern](#endpoint-pattern)

Every request is a `GET` to an endpoint that follows the same pattern.

```text
GET /direct-web-services/time-series/v1/{category}/{data-point}/{ids}
```

The category and data point select what you retrieve, and `{ids}` holds the investments. All other inputs are query parameters. Use the base URL for your region, as described in [Getting Started](https://developer-beta.morningstar.com/time-series-api/getting-started).

### [Headers](#headers)

| Header        | Value                                                                            |
| :------------ | :------------------------------------------------------------------------------- |
| Authorization | Bearer {token}. Obtain a token from POST /token/oauth and reuse it for up to 60 minutes. |
| Content-Type  | application/json                                                                 |

## [Request Steps](#request-steps)

Build a request in the following steps.

1.  **Choose a data point.** The data point determines the endpoint and the type of observation returned. See [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point).
2.  **Specify the investments.** Pass up to 25 identifiers in the path, and use `idTypes` and the lookup filters when you aren't using Performance IDs. See [Specify Investments](https://developer-beta.morningstar.com/time-series-api/specify-investments).
3.  **Set the time range and frequency.** Use dates, a relative period or since inception, and choose how often observations are returned. See [Set the Time Range](https://developer-beta.morningstar.com/time-series-api/set-the-time-range).
4.  **Add computed data point parameters.** Only needed for `return`, `cumulative-return`, `rolling-return`, `growth` and `price`. See [Configure Computed Data Points](https://developer-beta.morningstar.com/time-series-api/configure-computed-data-points).
5.  **Set the output currency**, if you don't want data in the investment's base currency. See [Output Currency](#output-currency).

## [Example Request](#example-request)

The following request retrieves monthly returns for three investments over a fixed date range, in US dollars.

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

## [Output Currency](#output-currency)

Use the `currencyId` query parameter to set the currency of the returned data.

| Value           | Description                                                           |
| :-------------- | :-------------------------------------------------------------------- |
| BAS             | Default. Returns data in the investment's base currency.              |
| A currency code | Returns data converted to that currency, for example USD, EUR or JPY. |

For the full list of supported values, see [API Inputs](https://developer-beta.morningstar.com/time-series-api/api-inputs).

## [Request Limits](#request-limits)

-   A request can include a maximum of **25 investments**.
-   Each request is limited by how far back it can look, which depends on the frequency and on whether the data point is univariate or multivariate. See [Lookback Limits](https://developer-beta.morningstar.com/time-series-api/set-the-time-range#lookback-limits).

Requests that exceed these limits must be split into multiple calls.

## [Responses](#responses)

| Status | Description                                                                      |
| :----- | :------------------------------------------------------------------------------- |
| 200    | The request succeeded. The body contains an investments array and a metadata object. See Work with Results. |
| 400    | The request is invalid.                                                          |
| 500    | Internal server error.                                                           |

Error responses contain a `statusCode`, an `errorCode`, a `message` and a `requestId`.

```json
{
  "statusCode": 400,
  "errorCode": "400.timeSeries.009",
  "message": "Invalid frequency 'm' for datapoint 'daily-closing-price'.",
  "requestId": "c63e7f6c-b52d-42c3-9d1b-4a4b4ac05f3c"
}
```

Include the `requestId` if you contact support. For the meaning of each error, see [Errors](https://developer-beta.morningstar.com/time-series-api/error-messages).

## [In This Section](#in-this-section)

| Page                           | Description                                                                    |
| :----------------------------- | :----------------------------------------------------------------------------- |
| Specify Investments            | Identify investments with IDs, identifier types and lookup filters.            |
| Set the Time Range             | Choose the frequency and time range, and align start dates across investments. |
| Configure Computed Data Points | Set the parameters for data points that are calculated at request time.        |