Universe API

Retrieve investment identifiers in your entitled universe.

Work with Results

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.

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

When a request has no primary filter, investments is empty, and metadata lists your entitlements. See Get Your Universe 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

The following response is a page of equities. The list is shortened.

{
  "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.

{
  "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

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

A response contains up to 50 investments, or the number set by pageSize. To retrieve the whole universe:

Send the first request with your filters, and read metadata.paginationTokenNext.
If the token is present, send the same request again, with the token in the paginationTokenNext query parameter.
Repeat until a response has no paginationTokenNext. You have then retrieved the whole universe for those filters.

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

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.

{
  "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. For help with common problems, see Troubleshooting.

Next Steps

Filter Values lists the accepted values for the filters.
Troubleshooting helps when a response isn't what you expected.