--- title: "FAQs" description: "Answers to common questions about the Equities Screener API: scope, filters, data points, pagination and results." url: "https://developer-beta.morningstar.com/equities-screener-api/faqs" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RkFRcyB8IEVxdWl0aWVzIFNjcmVlbmVyIEFQSQ,description_~QW5zd2VycyB0byBjb21tb24gcXVlc3Rpb25zIGFib3V0IHRoZSBFcXVpdGllcyBTY3JlZW5lciBBUEk6IHNjb3BlLCBmaWx0ZXJzLCBkYXRhIHBvaW50cywgcGFnaW5hdGlvbiBhbmQgcmVzdWx0cy4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvZmFxcyI,s_E6uuFCo5v6YC84OX.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) # Equities Screener API Powerful, criteria-based screening using flexible filtering logic. # FAQs [View Markdown](https://developer-beta.morningstar.com/equities-screener-api/faqs.md)[Download Markdown](https://developer-beta.morningstar.com/equities-screener-api/faqs.md) Answers to common questions about the Equities Screener API. If a request fails or returns unexpected results, see [Troubleshooting](https://developer-beta.morningstar.com/equities-screener-api/troubleshooting). ## [General](#general) What does the Equities Screener API do? It finds equities that match criteria you define. You set the starting universe with a scope, narrow it with filter conditions, and choose the data points to return for each match. The response includes the matching investments and their performance IDs, which you can use in other APIs. See [Core Concepts](https://developer-beta.morningstar.com/equities-screener-api/core-concepts). --- What endpoints does the API have? The API has two endpoints. | Endpoint | Purpose | | :--------------------------------------------------------- | :------------------------------------------------------ | | POST /direct-web-services/v1/screeners/equities | Runs a screen and returns the data points you select. | | GET /direct-web-services/v1/screeners/equities/data-points | Lists the data points you can use, with their metadata. | 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` --- Can I use the results with other APIs? Yes. Each match includes its performance ID, which is the primary identifier used by other Morningstar APIs. Pass the performance IDs to another API to retrieve more data. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results). --- Should I use this API to get data for investments I already know? No. The Equities Screener API is for finding investments that meet criteria. If you already have performance IDs and want data for those investments, use an API designed for that, such as the [Investment List API](https://developer-beta.morningstar.com/investment-list-api) for list-based data or the [Time Series API](https://developer-beta.morningstar.com/time-series-api) for history. --- ## [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. Long-running jobs must request a new token before it expires, and retry any request that returns `401 Unauthorized`. --- ## [Scope and Filters](#scope-and-filters) What is the scope, and do I need one? The scope sets the starting universe of investments, limited to your entitled universe. A request must include one. For equities, it is defined with the exchange code data point, `shareClassInformation.exchangeCode`. See [Screen Equities](https://developer-beta.morningstar.com/equities-screener-api/screen-equities#step-1-define-the-scope). --- Is the query required? No. If you omit `query`, no filtering is applied beyond your entitled universe and the scope. --- Which operators can I use? You can use equality filters (a single value, or a list of values), comparison filters (`gt`, `gte`, `lt` and `lte`) and compound filters (`and`, `or` and `not`). Some text data points also support `contains` and fuzzy search. See [Operators](https://developer-beta.morningstar.com/equities-screener-api/operators). --- How do I match several values? Use a list. An investment is returned if its value equals any entry in the list. ```json "query": { "shareClassInformation.symbol": ["MSES", "CA40"] } ``` --- How do I combine conditions? Use `and`, `or` and `not`, which each take an array of conditions. They can be nested. ```json "query": { "and": [ { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] }, { "marketCapital.asOfDate": { "gt": "2020-01-01" } } ] } ``` See [Compound Filters](https://developer-beta.morningstar.com/equities-screener-api/compound-filters). --- How do I find out which operators a data point supports? Check the `operators` property in the data point's metadata. It lists the operators that the data point supports. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points). --- Does fuzzy search work on every text data point? No. Fuzzy search works only on some string data points, only as an equality filter, and the search text must be at least 3 characters. See [Equality and Text Filters](https://developer-beta.morningstar.com/equities-screener-api/equality-and-text-filters#use-fuzzy-search). --- ## [Data Points](#data-points) How do I find valid data point names? Call the data points endpoint. It lists every data point with its data type, operators, sortability and language and currency dependencies. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points). --- How many data points can I return in one request? Up to 100. If you omit `dataPoints`, only the performance ID is returned. --- Is the performance ID always returned? Yes. It is returned in every match as `instrumentIdentifiers.performanceId`, whether or not you ask for it. --- What are language-dependent and currency-dependent data points? These are data points whose values depend on a language or a currency. Pass `languageId` to retrieve language-dependent data points (the default is `ENG`) and `currencyId` to retrieve currency-dependent ones (the default is `USD`). The metadata for each data point shows whether it has either dependency. --- Can I sort by any data point? No. The data point must be sortable, which its metadata shows, and it must also be in the `dataPoints` array of the request. --- ## [Pagination and Sorting](#pagination-and-sorting) What is the default sort order? Results are sorted by performance ID in ascending order. To change this, use the `sort` array. See [Screen Equities](https://developer-beta.morningstar.com/equities-screener-api/screen-equities#step-4-set-sort-preferences). --- How many results are returned per page? The default and maximum is 50. Set `pagination.pageSize` to return fewer. --- How do I retrieve the next page? Take the `paginationTokenNext` value from the `metadata` of the response, and send the same request again with the token in `pagination.paginationTokenNext`. ```json "pagination": { "pageSize": 25, "paginationTokenNext": "{token from the previous response}" } ``` --- How do I find out how many investments matched? Read `metadata.totalCount`. It is the total number of matches across all pages. --- How do I know when I have reached the last page? The response has no `paginationTokenNext`. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results#use-the-result-count-and-pagination-tokens). --- Can I use both pagination tokens in one request? No. Use either `paginationTokenNext` or `paginationTokenPrevious` in a request. --- ## [Responses](#responses) How is the response structured? The response has an `investments` array, with one object for each match on the page, and a `metadata` object. Each investment is a flat object keyed by data point name. The metadata contains `totalCount`, the pagination tokens, any warnings in `messages`, the `requestId` and the `time`. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results). --- Does a 200 response mean every data point was returned? No. If you aren't entitled to a data point for an investment, the investment is still returned without it, and a warning in `metadata.messages` lists the data points that couldn't be returned. Always check `metadata.messages`. --- What is the requestId for? It is a unique identifier for the request. It is returned in the response `metadata`, and in error responses. Include it if you contact support. ---