Get Your Universe

The Universe API has one endpoint, and you use it in different ways depending on the query parameters you send. This page walks through the main ways to use it. For the ideas behind them, see Core Concepts.

Request Overview

To retrieve your universe, send a GET request to the investments endpoint.

GET /direct-web-services/v1/investments

Use the base URL for your region, as described in Getting Started. The request must include your access token in the Authorization header. All other inputs are query parameters.

The query parameters fall into the following groups.

Step 1: Get Your Entitlements

Send a request with no filters to find out what you are entitled to. The response contains no investments. It lists the values that you can use as primary filters.

For equities, send the request with no parameters. Equities are the default.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments" \
  --header "Authorization: Bearer {token}"

For managed investments, set source to managedInvestments.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?source=managedInvestments" \
  --header "Authorization: Bearer {token}"

The response for equities lists the exchanges, with their market identifier codes (MICs), and the countries and domiciles you are entitled to. The list is shortened here.

{
  "investments": [],
  "metadata": {
    "requestId": "68511d05-3d2e-480c-ae88-a14be0948f03",
    "time": "2026-02-26T12:19:15.8950456Z",
    "exchanges": [
      {
        "exchangeCode": "SWA",
        "micCode": "XSWA"
      },
      {
        "exchangeCode": "XTER",
        "micCode": "XETR"
      },
      {
        "exchangeCode": "KAR",
        "micCode": "XKAR"
      }
    ],
    "countryAvailableForSale": [
      "ABW",
      "AFG",
      "AGO"
    ],
    "domiciles": [
      "ABW",
      "AFG",
      "AGO"
    ]
  }
}

The response for managed investments lists the countries available for sale and the domiciles.

{
  "investments": [],
  "metadata": {
    "requestId": "19869bfc-fb97-4517-b19b-a212df8f6e4c",
    "time": "2026-02-26T12:40:36.1819168Z",
    "countryAvailableForSale": [
      "ABW",
      "AFG",
      "AGO"
    ],
    "domiciles": [
      "ABW",
      "AFG",
      "AGO"
    ]
  }
}

Use these values in the next step. Which lists are returned depends on your entitlements. See Work with Results.

Step 2: Filter the Universe

To list investments, choose a primary filter. You can then add secondary filters.

Choose a Primary Filter

The primary filter sets the top-level scope of the results. It is required, and a request can use only one.

Add Secondary Filters

Secondary filters are optional. They narrow the results within the scope of the primary filter, so they can't be used without one. You can combine several in one request.

For the accepted values, see Filter Values.

Examples

The following request lists the equities on one exchange.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?exchangeCode=XPAR" \
  --header "Authorization: Bearer {token}"

The following request lists the common stocks on that exchange, using a secondary filter.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?exchangeCode=XPAR&securityType=ST00000001" \
  --header "Authorization: Bearer {token}"

The following request lists the bond funds domiciled in the USA.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?source=managedInvestments&domicileCode=USA&investmentType=BD" \
  --header "Authorization: Bearer {token}"

Step 3: Use a Custom Universe

A custom universe is a named subset of your entitled universe that was set up for your account. Set universe to its name to retrieve it.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?universe=MY_EQUITIES_ABC" \
  --header "Authorization: Bearer {token}"

For managed investments, set source as well.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?source=managedInvestments&universe=MY_MANAGED_INVESTMENTS_XYZ" \
  --header "Authorization: Bearer {token}"

To narrow a custom universe, add a primary filter, and secondary filters if you need them. For example, universe=MY_EQUITIES_ABC&exchangeCode=XPAR&securityType=ST00000001.

Step 4: Set the Page Size

Each response contains up to 50 investments. Set pageSize, from 1 to 50, to change this. The default is 50.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments?exchangeCode=XPAR&pageSize=25" \
  --header "Authorization: Bearer {token}"

If there are more investments, the response contains a pagination token. See Work with Results.

Request Scenarios

The following table summarizes the requests you can make. All start with GET /direct-web-services/v1/investments.

Errors

A request that isn't valid returns a 400 with an error code and a message. For example, a filter that doesn't suit the investment type returns Invalid source input for domicileCode. See Error Messages and Troubleshooting.

Next Steps

• Work with Results explains how to read the response and page through the results.
• API Inputs is a quick reference for every input.