# Universe API Retrieve your entitled investment universe and performance IDs. {.sub-title___devsite} ## Overview The Universe API is the discovery layer for the Investment Details API. Use it to identify all investments you are entitled to access and retrieve the performance IDs required to make downstream calls. ## Endpoints | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/direct-web-services/v1/investments` | Retrieve your entitled investment universe, filtered by exchange or country. | ## How It Works - **Your universe is scoped to your entitlements.** The investments returned are specific to your account. Filters available to you reflect only what you are entitled to access. - **Performance IDs are the key identifier.** Every investment in the response includes a `performanceId`. This is a stable, global identifier used across all Morningstar datasets. Use it as your primary key when storing and referencing investments. - **Results are paginated using tokens.** Responses return up to 50 investments at a time, along with a `paginationTokenNext` token if more results exist. Pass this token in your next request to continue from the exact position in the dataset. Stop when no token is returned. ## Quick Start **Step 1 — Discover your available filters** Retrieve the list of universes (exchanges or countries) available to your account.

curl --location \
--request GET 'https://www.us-api.morningstar.com/direct-web-services/v1/investments?source=equities' \
--header 'Authorization: Bearer {access_token}'

**Step 2 — Filter the universe** Use a filter from the metadata response to retrieve investments.

curl --location \
--request GET 'https://www.us-api.morningstar.com/direct-web-services/v1/investments?source=equitiess&exchangeCode=XPAR&pageSize=50' \
--header 'Authorization: Bearer {access_token}'

**Step 3 — Page through the full universe** If `paginationTokenNext` is present, pass it in your next request. Repeat until the token is no longer returned:

curl --location \
--request GET 'https://www.us-api.morningstar.com/direct-web-services/v1/investments?source=equitiess&exchangeCode=XPAR&pageSize=50&paginationTokenNext={token}' \
--header 'Authorization: Bearer {access_token}'

## Best Practices - Keep all original filter parameters the same across paginated requests. Only the pagination token should change between calls. - Do not modify or attempt to decode pagination tokens. Pass them back exactly as received. ## Troubleshooting & FAQs

How do I retrieve more than 50 investments?

Results are paginated. If a paginationTokenNext token is present in the response metadata, pass it as a query parameter in your next request. Keep all other filters the same and repeat until no token is returned — at that point you have retrieved the full universe for that filter.

Can I decode or manipulate pagination tokens?

No. Pagination tokens are opaque and should be passed back exactly as received. Modifying a token may result in an error or unexpected results.

## Related Content - [API Reference](/direct-web-services/documentation/api-utilities/universe-api/api-reference)