--- title: "Work with Results" description: "Read a Time Series API response: its structure, observation types, how to match results to investments and how to handle unmatched investments." url: "https://developer-beta.morningstar.com/time-series-api/work-with-results" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~V29yayB3aXRoIFJlc3VsdHMgfCBUaW1lIFNlcmllcyBBUEk,description_~UmVhZCBhIFRpbWUgU2VyaWVzIEFQSSByZXNwb25zZTogaXRzIHN0cnVjdHVyZSwgb2JzZXJ2YXRpb24gdHlwZXMsIGhvdyB0byBtYXRjaCByZXN1bHRzIHRvIGludmVzdG1lbnRzIGFuZCBob3cgdG8gaGFuZGxlIHVubWF0Y2hlZCBpbnZlc3RtZW50cy4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii90aW1lLXNlcmllcy1hcGkvd29yay13aXRoLXJlc3VsdHMi,s_zGcFUim6i6MFoi9H.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. # Work with Results [View Markdown](https://developer-beta.morningstar.com/time-series-api/work-with-results.md)[Download Markdown](https://developer-beta.morningstar.com/time-series-api/work-with-results.md) A successful request returns a JSON object with the time series for each investment that returned data, plus metadata about the request. This page explains how to read the response, how to parse the observations, and how to check for investments that returned no data. ## [Response Structure](#response-structure) The response has two top-level properties. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | investments | An array with one object for each investment that returned data. | | metadata | Information about the request, including warnings about identifiers that returned no results. | Each object in `investments` contains the following properties. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | identifiers | The identifiers of the investment, including the one you passed in the request. | | timeSeries | The time series for the requested data point. | | metadata | The lookup values used to find the investment: exchangeCountry, domicile and baseCurrency. | Each `timeSeries` object contains the following properties. | Property | Description | | :-------------- | :------------------------------------------------------------------------------- | | categories | The category of the data point, for example performance. | | dataPoint | The data point name, for example daily-price. | | performanceType | The performance type used in the calculation: total, market or gross. Present for computed data points. | | data | The array of observations. Its shape depends on the data point. | The following response is for a request for `daily-price` with two investments, where one identifier returned no data. ```json { "investments": [ { "identifiers": { "performanceId": "0P00000CSY" }, "timeSeries": { "categories": ["performance"], "dataPoint": "daily-price", "data": [ { "date": "2025-01-02", "value": 0.71234 }, { "date": "2025-01-03", "value": 0.72108 } ] }, "metadata": { "exchangeCountry": "USA", "domicile": "USA", "baseCurrency": "USD" } } ], "metadata": { "messages": { "investments": [ { "id": "0P000PPP6Q", "idType": "performanceId" } ], "type": "Warning", "message": "Lookup : Invalid investments.", "code": "404.common.125" }, "requestId": "f1a94c72-3d08-4b61-9e21-2c85da673f10", "time": "2025-10-30T14:25:47.883412Z" } } ``` ## [Identify the Observation Type](#identify-the-observation-type) The shape of the `data` array depends on the data point. Use the `dataPoint` value in each `timeSeries` object to decide how to parse it. **Univariate observations** are returned by most data points. Each observation contains a `date` and a single `value`. ```json { "data": [ { "date": "2025-01-31", "value": 0.02341 }, { "date": "2025-02-28", "value": -0.01204 } ] } ``` **Multivariate observations** are returned by `daily-ohlcv` only. Each observation contains a `date` and separate fields for the open, high, low and closing price and the volume. ```json { "data": [ { "date": "2025-01-02", "dailyOpenPrice": 5.17, "dailyHighPrice": 5.21, "dailyLowPrice": 5.14, "dailyClosingPrice": 5.19, "dailyVolume": 130918 } ] } ``` You choose the observation type by choosing the data point, not through a request parameter. For more detail, see [Core Concepts](https://developer-beta.morningstar.com/time-series-api/core-concepts#univariate-and-multivariate-observations). ## [Match Results to Investments](#match-results-to-investments) Investments that can't be matched don't return data, so the `investments` array may contain fewer entries than the values you sent in `ids`. Match each result to your request using the values in `identifiers`, not the position of the entry in the array. ## [Handle Unmatched Investments](#handle-unmatched-investments) A `200` status code doesn't guarantee that every requested investment returned data. If the API can't match an identifier to an investment, it returns no data for that investment and lists it in `metadata.messages`. Always check this object when you process a response. `metadata.messages` contains the following properties. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | investments | The identifiers that returned no results. Each entry has the id you passed and its idType. | | type | The message type. The value is Warning. | | message | A description of the issue. | | code | The warning code. | The following warning codes can be returned. | Code | Message | What to Do | | :------------- | :------------------------------------------------------------ | :----------------------------------------------------------------- | | 404.common.125 | Lookup : Invalid investments. | Check the identifier values and the lookup filters in the request. | | 200.common.126 | Lookup : Multiple identifier match found for the investments. | Add lookup filters to narrow each identifier to one investment. | | 200.common.128 | Duplicate investments found in the request. | Remove duplicate identifiers from the request. | For how identifiers and lookup filters are matched, see [Specify Investments](https://developer-beta.morningstar.com/time-series-api/specify-investments). ## [Response Metadata](#response-metadata) The top-level `metadata` object also contains the following properties. | Property | Description | | :-------- | :----------------------------------------------------------------------- | | requestId | The unique identifier of the request. Include it if you contact support. | | time | The time the response was returned. | ## [Handle Errors](#handle-errors) A request that fails returns an error response instead of time series data. The response contains the following properties. | Property | Description | | :--------- | :---------------------------------------- | | statusCode | The HTTP status code, such as 400 or 500. | | errorCode | An identifier for the type of error. | | message | A description of the problem. | | requestId | The unique identifier of the request. | ```json { "statusCode": 400, "errorCode": "400.timeSeries.009", "message": "Invalid frequency 'm' for datapoint 'daily-closing-price'.", "requestId": "c63e7f6c-b52d-42c3-9d1b-4a4b4ac05f3c" } ``` For the meaning of each error and how to resolve it, see [Errors](https://developer-beta.morningstar.com/time-series-api/error-messages) and [Troubleshooting](https://developer-beta.morningstar.com/time-series-api/troubleshooting).