--- title: "FAQs" description: "Answers to common questions about the Universe API: entitlements, primary and secondary filters, custom universes and pagination." url: "https://developer-beta.morningstar.com/universe-api/faqs" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RkFRcyB8IFVuaXZlcnNlIEFQSQ,description_~QW5zd2VycyB0byBjb21tb24gcXVlc3Rpb25zIGFib3V0IHRoZSBVbml2ZXJzZSBBUEk6IGVudGl0bGVtZW50cywgcHJpbWFyeSBhbmQgc2Vjb25kYXJ5IGZpbHRlcnMsIGN1c3RvbSB1bml2ZXJzZXMgYW5kIHBhZ2luYXRpb24u,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii91bml2ZXJzZS1hcGkvZmFxcyI,s_QxpbOqHluK9ogw49.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. # FAQs [View Markdown](https://developer-beta.morningstar.com/universe-api/faqs.md)[Download Markdown](https://developer-beta.morningstar.com/universe-api/faqs.md) Answers to common questions about the Universe API. If a request fails or returns unexpected results, see [Troubleshooting](https://developer-beta.morningstar.com/universe-api/troubleshooting). ## [General](#general) What does the Universe API do? It returns the investments in your entitled universe, and the performance IDs that other APIs use to identify them. You can also use it to find out which exchanges, countries and domiciles you are entitled to. See [Core Concepts](https://developer-beta.morningstar.com/universe-api/core-concepts). --- Why do I need the Universe API? The Investment Details, Investment List and Time Series APIs use Morningstar Performance IDs as their primary identifier. The Universe API gives you the performance IDs for the investments you are entitled to, so that you can use them in those APIs. See the [Identifiers](https://developer-beta.morningstar.com/api-identifiers) article. --- What endpoint does the API have? The API has one endpoint: `GET /direct-web-services/v1/investments`. What it returns depends on the query parameters you send. Use the base URL for your region. - Americas: `https://www.us-api.morningstar.com` - APAC: `https://www.apac-api.morningstar.com` - EMEA: `https://www.emea-api.morningstar.com` --- How is it different from the Screener APIs? The Universe API lists the investments you are entitled to, by exchange, country or domicile. The [Screener APIs](https://developer-beta.morningstar.com/screener-apis) find investments that meet criteria that you define, using their data points. --- ## [Authentication](#authentication) How do I authenticate? Request a token from `POST /token/oauth`, then send it on every other request in the `Authorization` header as `Bearer {token}`. See [Authentication](https://developer-beta.morningstar.com/api-authentication). --- How long does an access token last? A token is valid for 60 minutes and can be reused across requests during that time. A job that pages through a large universe must request a new token before it expires, and retry any request that returns `401 Unauthorized`. --- ## [Entitlements and Filters](#entitlements-and-filters) How do I find out what I am entitled to? Send a request with no filters. The response lists the exchanges, countries and domiciles you are entitled to, which are the values you can use as primary filters. Use `source=managedInvestments` for managed investments. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-1-get-your-entitlements). --- Why does my response contain no investments? A request with no primary filter returns your entitlements, not investments, so the `investments` array is empty. Add a primary filter, such as `exchangeCode` for equities, to list investments. See [Work with Results](https://developer-beta.morningstar.com/universe-api/work-with-results#entitlements-response). --- What is a primary filter? A primary filter sets the top-level scope of the results. It is required to list investments, and a request can use only one. For equities it is `exchangeCode`. For managed investments it is `countryAvailableForSaleCode` or `domicileCode`. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-2-filter-the-universe). --- What is a secondary filter? A secondary filter narrows the results within the scope of the primary filter. It is optional, it can't be used without a primary filter, and you can combine several. For equities they are `securityType` and `shareClassInformationInvestmentType`. For managed investments they are `investmentType`, `fundLegalStructureName` and `exchange`. See [Filter Values](https://developer-beta.morningstar.com/universe-api/filter-values) for the accepted values. --- How do I retrieve managed investments? Set the `source` parameter to `managedInvestments`. The default is `equities`. --- What is a custom universe? A custom universe is a named subset of your entitled universe, set up for your account. Set `universe` to its name to retrieve it, and add filters to narrow it further. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-3-use-a-custom-universe). --- Where can I find the accepted filter values? See [Filter Values](https://developer-beta.morningstar.com/universe-api/filter-values) for source, security type, investment type and fund legal structure. Exchange codes, countries and domiciles are the ones in your entitlements. --- ## [Results and Pagination](#results-and-pagination) How many investments does a response contain? Up to 50, which is also the default. Set `pageSize`, from 1 to 50, to change it. --- How do I retrieve more than 50 investments? If the response contains `paginationTokenNext`, pass it in the `paginationTokenNext` parameter of your next request. Keep all the other parameters the same, and repeat until no token is returned. See [Work with Results](https://developer-beta.morningstar.com/universe-api/work-with-results#page-through-the-results). --- How do I know I have retrieved everything? When a response has no `paginationTokenNext`, you have retrieved the whole universe for those filters. --- Can I decode or change a pagination token? No. Pagination tokens are opaque, so pass them back exactly as you received them. Changing a token may cause an error or unexpected results. --- What is totalCount? It is the total number of investments found for your filters, across all pages. Use it with your page size to estimate the number of pages. --- ## [Using the Results](#using-the-results) Which identifier should I store? Store the performance ID, which is stable and is the primary identifier in other APIs. Use it as the key when you store and reference investments. --- How do I use the results with other APIs? Pass the performance IDs to the [Investment Details API](https://developer-beta.morningstar.com/investment-details-api), the [Investment Details Feed API](https://developer-beta.morningstar.com/investment-details-feed-api), the [Investment List API](https://developer-beta.morningstar.com/investment-list-api) or the [Time Series API](https://developer-beta.morningstar.com/time-series-api). ---