--- title: "Work with Results" description: "Read a Universe API response: the investments, the entitlements metadata, pagination tokens, the total count and error responses." url: "https://developer-beta.morningstar.com/universe-api/work-with-results" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~V29yayB3aXRoIFJlc3VsdHMgfCBVbml2ZXJzZSBBUEk,description_~UmVhZCBhIFVuaXZlcnNlIEFQSSByZXNwb25zZTogdGhlIGludmVzdG1lbnRzLCB0aGUgZW50aXRsZW1lbnRzIG1ldGFkYXRhLCBwYWdpbmF0aW9uIHRva2VucywgdGhlIHRvdGFsIGNvdW50IGFuZCBlcnJvciByZXNwb25zZXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii91bml2ZXJzZS1hcGkvd29yay13aXRoLXJlc3VsdHMi,s_f53qw3abDhAXsOP0.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) # Universe API Retrieve investment identifiers in your entitled universe. # Work with Results [View Markdown](https://developer-beta.morningstar.com/universe-api/work-with-results.md)[Download Markdown](https://developer-beta.morningstar.com/universe-api/work-with-results.md) A request returns either your entitlements or a page of investments, along with metadata. This page explains how to read both kinds of response, and how to page through a large universe. For how to build requests, see [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe). ## [Response Structure](#response-structure) Every response has two top-level properties. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | investments | An array with one object for each investment on the page. It is empty when you send no primary filter. | | metadata | Information about the response: the request ID, the time, the total count, pagination tokens and your entitlements. | ## [Entitlements Response](#entitlements-response) When a request has no primary filter, `investments` is empty, and `metadata` lists your entitlements. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-1-get-your-entitlements) for examples. | Property | Description | | :------------------------------- | :------------------------------------------------------------------------------- | | metadata.exchanges | The exchanges you are entitled to, each with an exchangeCode and a micCode. Returned for equities. | | metadata.countryAvailableForSale | The countries available for sale that you are entitled to. | | metadata.domiciles | The domiciles that you are entitled to. | ## [Read the Investments](#read-the-investments) The following response is a page of equities. The list is shortened. ```json { "investments": [ { "identifiers": { "performanceId": "0P0000CJZY" }, "companyInformation": { "companyId": "0C000007ZR", "standardName": "KB Financial Group Inc" }, "shareClassInformation": { "exchangeCode": "XTER", "investmentId": "E0KOR01R2U", "isin": "US48241A1051", "securityType": "ST00000001", "symbol": "KBIA", "tradingCurrency": "EUR" } } ], "metadata": { "paginationTokenNext": "CJjVEBoTOhE3YyBzb2xhcnBh...", "totalCount": 11171, "requestId": "1bb636c2-f182-420c-bea2-9a0f46b53ab7", "time": "2026-02-26T12:35:39.1288129Z" } } ``` Each object in `investments` is one investment. It has the following characteristics. - **Identifiers.** The `identifiers` object holds the identifier of the investment, such as its performance ID. Store it, and use it in other APIs. - **Data groups.** The other properties are data groups. Equities have `companyInformation` and `shareClassInformation`, and can have `delistInformation`. Managed investments have `basicReference`. - **Coded values.** Some values are returned as an object with a `value` and a `code`, for example `{ "value": "US Dollar", "code": "USD" }`. The following response is a page of managed investments. The list is shortened. ```json { "investments": [ { "identifiers": { "securityId": "F00001DC2E" }, "basicReference": { "performanceId": "0P0001O9X4", "fundLegalName": "-1x Short VIX Futures ETF", "isin": "US92891H1014", "baseCurrency": { "value": "US Dollar", "code": "USD" }, "domicile": { "value": "United States", "code": "USA" }, "investmentType": { "value": "Exchange-Traded Fund", "code": "FE" } } } ], "metadata": { "paginationTokenNext": "WyIxIFhDRiBJbmN1YmF0b3Ii...", "totalCount": 441961, "requestId": "ed74051f-5274-4eee-9ef6-21fc754823b5", "time": "2026-02-26T12:46:12.1182492Z" } } ``` ## [Use the Metadata](#use-the-metadata) | Property | Description | | :---------------------- | :------------------------------------------------------------------------------- | | requestId | The unique identifier of the request. Include it if you contact support. | | time | The time the response was returned. | | totalCount | The total number of investments found, across all pages. | | paginationTokenNext | The token for the next page. It is present only when there are more investments. | | paginationTokenPrevious | The token for the previous page. | ## [Page Through the Results](#page-through-the-results) A response contains up to 50 investments, or the number set by `pageSize`. To retrieve the whole universe: 1. Send the first request with your filters, and read `metadata.paginationTokenNext`. 2. If the token is present, send the same request again, with the token in the `paginationTokenNext` query parameter. 3. Repeat until a response has no `paginationTokenNext`. You have then retrieved the whole universe for those filters. ```bash curl --request GET \ --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?exchangeCode=XPAR&pageSize=50&paginationTokenNext={token}" \ --header "Authorization: Bearer {token}" ``` To go back a page, use the `paginationTokenPrevious` value in the `paginationTokenPrevious` parameter instead. Follow these rules. - Keep all the original filter parameters the same across requests. Only the token should change. - Don't modify or try to decode a token. Pass it back exactly as you received it. - Use `totalCount` and your page size to estimate the number of pages. For example, 11,171 investments with a page size of 50 is 224 pages. ## [Handle Errors](#handle-errors) A request that fails returns an error response. | Property | Description | | :--------- | :------------------------------------ | | statusCode | The HTTP status code. | | errorCode | A unique identifier for the error. | | message | A description of the problem. | | requestId | The unique identifier of the request. | ```json { "statusCode": 400, "errorCode": "400.investmentDetails.020", "message": "Invalid source input for domicileCode", "requestId": "539d62a5-3586-4070-965e-0f7f64712d79" } ``` For the meaning of each error code, see [Error Messages](https://developer-beta.morningstar.com/universe-api/error-messages). For help with common problems, see [Troubleshooting](https://developer-beta.morningstar.com/universe-api/troubleshooting). ## [Next Steps](#next-steps) - [Filter Values](https://developer-beta.morningstar.com/universe-api/filter-values) lists the accepted values for the filters. - [Troubleshooting](https://developer-beta.morningstar.com/universe-api/troubleshooting) helps when a response isn't what you expected.