--- title: "FAQs" description: "Answers to common questions about the Time Series API: data points, investments, time ranges, computed data points and responses." url: "https://developer-beta.morningstar.com/time-series-api/faqs" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RkFRcyB8IFRpbWUgU2VyaWVzIEFQSQ,description_~QW5zd2VycyB0byBjb21tb24gcXVlc3Rpb25zIGFib3V0IHRoZSBUaW1lIFNlcmllcyBBUEk6IGRhdGEgcG9pbnRzLCBpbnZlc3RtZW50cywgdGltZSByYW5nZXMsIGNvbXB1dGVkIGRhdGEgcG9pbnRzIGFuZCByZXNwb25zZXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii90aW1lLXNlcmllcy1hcGkvZmFxcyI,s_lKmsKv2O9yrItjN0.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. # FAQs [View Markdown](https://developer-beta.morningstar.com/time-series-api/faqs.md)[Download Markdown](https://developer-beta.morningstar.com/time-series-api/faqs.md) Answers to common questions about the Time Series API. If a request fails or returns unexpected results, see [Troubleshooting](https://developer-beta.morningstar.com/time-series-api/troubleshooting). ## [General](#general) What does the Time Series API do? It returns historical time series data for investments, such as prices, returns, yields, ratings, fees and sustainability metrics. Each data point has its own endpoint, grouped into categories, and each request retrieves one data point for up to 25 investments. See [Core Concepts](https://developer-beta.morningstar.com/time-series-api/core-concepts). --- Which endpoint do I call? Every endpoint is a `GET` 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. Use the base URL for your region, as described in [Getting Started](https://developer-beta.morningstar.com/time-series-api/getting-started). To find the endpoint you need, see [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point). --- Is the API synchronous? Yes. The data is returned in the response to the same request. --- Can I try the API before I buy it? Yes. You can create an account to get credentials and test the endpoints. Trial responses are limited to a sample of real data from a sample universe. For full data coverage and production access, contact Morningstar sales. See [Getting Started](https://developer-beta.morningstar.com/time-series-api/getting-started). --- ## [Authentication](#authentication) How do I authenticate? Authentication has two steps. First, request a token from `POST /token/oauth`, using your Client ID and Client Secret as HTTP Basic credentials. Then send the token on every other request in the `Authorization` header as `Bearer {token}`. See [Getting Started](https://developer-beta.morningstar.com/time-series-api/getting-started). --- Where do I get a Client ID and Client Secret? Create an application in your portal profile. The application issues the Client ID and Client Secret. They are separate from the username and password you use to log in to Morningstar for Developers. --- How long does an access token last? A token is valid for 60 minutes and can be reused across requests during that time. Long-running jobs must request a new token before it expires, and retry any request that returns `401 Unauthorized`. --- ## [Data Points](#data-points) How do I find the data point I need? There are several hundred data points in eight categories. You can browse by category, search by name, or use the naming patterns to tell similar data points apart. See [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point). --- Can I request more than one data point in a single request? No. Each request retrieves one data point. To retrieve several, make one request for each data point. --- Why does the same data point appear in more than one category? Some data points are available under more than one category, and each category has its own endpoint. Examples are `monthly-return` in `performance` and `fund-research`, and `daily-closing-price` in `reference` and `performance`. Read the description of each endpoint before you choose between them. See [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point#data-points-available-in-more-than-one-category). --- What is the difference between standard and computed data points? Standard data points return values from stored data and use only the general request parameters. Computed data points calculate their values when you make the request, and accept extra parameters that control the calculation. The computed data points are `return`, `cumulative-return`, `rolling-return`, `growth` and `price`. See [Core Concepts](https://developer-beta.morningstar.com/time-series-api/core-concepts#standard-and-computed-data-points). --- What does In Trial mean? The API reference lists some `performance` data points in a separate In Trial group, including `growth`, `price`, `monthly-return` and `quarterly-return`. See [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point#in-trial-status). --- ## [Investments](#investments) How many investments can I request at once? A maximum of 25 per request. To retrieve more, split them across several requests. --- Which identifiers can I use? Morningstar Performance ID (the default), Morningstar Security ID, MSID, ISIN, CUSIP and trading symbol. You can also pass category IDs, which must be URL-encoded. See [Specify Investments](https://developer-beta.morningstar.com/time-series-api/specify-investments). --- Can I mix identifier types in one request? Yes. Use `idTypes` to say what each value is. The list lines up with `ids` by position, empty entries default to `performanceId`, and trailing commas are omitted. ```text GET /direct-web-services/time-series/v1/performance/daily-price/US2562191062,MDLOX,0P00006W6Q ?idTypes=isin,tradingSymbol ``` --- What if an identifier matches more than one investment? Use the lookup filters `baseCurrency`, `domicile`, `exchangeCountry` and `exchangeId` to narrow the match. Each is a list that lines up with `ids` by position. The lookup values that were applied are returned in the `metadata` of each investment. See [Specify Investments](https://developer-beta.morningstar.com/time-series-api/specify-investments#narrow-the-lookup). --- What happens if one of my investments isn't found? The request still succeeds, but no data is returned for that investment. The unmatched identifiers are listed in `metadata.messages` in the response. See [Work with Results](https://developer-beta.morningstar.com/time-series-api/work-with-results#handle-unmatched-investments). --- ## [Time Range and Frequency](#time-range-and-frequency) Which frequencies are supported? `daily` (the default), `weekly`, `monthly`, `quarterly` and `annually`. Set the frequency with the `frequency` parameter. See [Set the Time Range](https://developer-beta.morningstar.com/time-series-api/set-the-time-range#frequency). --- How do I set the time range? You can use one of three approaches. - Pass `startDate` and `endDate` in `yyyy-MM-dd` format. - Pass `timePeriod` and `timePeriodUnit` (`days`, `months` or `years`) for a relative window. - Set `sinceInception` to `true` to request data since inception. See [Set the Time Range](https://developer-beta.morningstar.com/time-series-api/set-the-time-range#choose-a-time-range). --- What if I use more than one approach? `sinceInception` overrides `timePeriod`, `timePeriodUnit`, `startDate` and `endDate`. `timePeriod` and `timePeriodUnit` override `startDate` and `endDate`. --- How far back can I go? The maximum lookback depends on the frequency and the observation type. | 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 | Requests that go further back must be split into several requests. --- How do I get all the data since inception? Set `sinceInception` to `true`. The API returns data from the start of the investment's history, or from the maximum supported lookback, to the end date. `sinceInception` isn't supported for multivariate data points such as `daily-ohlcv`. --- How do I make several investments start on the same date? Set `applyEarliestCommonDate` to `true`. The start of every time series moves to the latest inception date among the requested investments. See [Set the Time Range](https://developer-beta.morningstar.com/time-series-api/set-the-time-range#align-start-dates). --- Can I get data in a different currency? Yes. Use the `currencyId` parameter. The default, `BAS`, returns data in the investment's base currency. See [Request Time Series Data](https://developer-beta.morningstar.com/time-series-api/request-time-series-data#output-currency). --- ## [Computed Data Points](#computed-data-points) What does performanceType do? It sets the performance stream used in a computed calculation: `total` (the default), `market` or `gross`. You can pass a second value as a fallback that is used if the first returns no data. The response returns the `performanceType` that was applied. See [Configure Computed Data Points](https://developer-beta.morningstar.com/time-series-api/configure-computed-data-points#performance-type). --- How do I get rolling returns? Use the `rolling-return` data point. Set `windowSize` for the length of the window and `stepSize` for how far it moves between calculations. ```text GET /direct-web-services/time-series/v1/performance/rolling-return/0P00000CSY ?startDate=2015-01-01 &endDate=2024-12-31 &frequency=monthly &windowSize=12 &stepSize=1 ``` --- Which parameters does each computed data point accept? Each computed data point accepts a different set of parameters. See the table in [Configure Computed Data Points](https://developer-beta.morningstar.com/time-series-api/configure-computed-data-points#which-parameters-apply). --- ## [Responses](#responses) How is the response structured? The response has an `investments` array, with one object for each investment that returned data, and a `metadata` object. Each investment has `identifiers`, a `timeSeries` object and `metadata`. See [Work with Results](https://developer-beta.morningstar.com/time-series-api/work-with-results). --- How do I know whether a data point returns one value or several? Use the `dataPoint` value in each `timeSeries` object. Almost every data point returns a `date` and a single `value`. Only `daily-ohlcv` returns several values per date. See [Work with Results](https://developer-beta.morningstar.com/time-series-api/work-with-results#identify-the-observation-type). --- Does a 200 response mean every investment returned data? No. If an identifier can't be matched, the request still returns `200`, and the unmatched identifiers are listed in `metadata.messages`. Always check `metadata.messages`. --- What is the requestId for? It is a unique identifier for the request. It is returned in the response `metadata` and in error responses. Include it if you contact support. ---