--- title: "Screen Equities" description: "Build and send an equity screen: define the scope, add filter conditions, select data points, set the sort order and page through results." url: "https://developer-beta.morningstar.com/equities-screener-api/screen-equities" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~U2NyZWVuIEVxdWl0aWVzIHwgRXF1aXRpZXMgU2NyZWVuZXIgQVBJ,description_~QnVpbGQgYW5kIHNlbmQgYW4gZXF1aXR5IHNjcmVlbjogZGVmaW5lIHRoZSBzY29wZSwgYWRkIGZpbHRlciBjb25kaXRpb25zLCBzZWxlY3QgZGF0YSBwb2ludHMsIHNldCB0aGUgc29ydCBvcmRlciBhbmQgcGFnZSB0aHJvdWdoIHJlc3VsdHMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvc2NyZWVuLWVxdWl0aWVzIg,s_Tny6CR5LAoYWosHw.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. # Screen Equities [View Markdown](https://developer-beta.morningstar.com/equities-screener-api/screen-equities.md)[Download Markdown](https://developer-beta.morningstar.com/equities-screener-api/screen-equities.md) A screen is one request that says where to look, what to look for and what to return. This page walks through building a complete request, one part at a time. For the ideas behind each part, see [Core Concepts](https://developer-beta.morningstar.com/equities-screener-api/core-concepts). ## [Request Overview](#request-overview) To run a screen, send a `POST` request to the screener endpoint. ```text POST /direct-web-services/v1/screeners/equities ``` Use the base URL for your region, as described in [Getting Started](https://developer-beta.morningstar.com/equities-screener-api/getting-started). The request must include the following headers. | Header | Value | | :------------ | :---------------------------------- | | Authorization | Bearer {token}. See Authentication. | | Content-Type | application/json | The body is a JSON object. Build it in the following steps. | Step | Property | Purpose | | :--- | :--------------------------------- | :------------------------------------------ | | 1 | scope | Sets the starting universe. | | 2 | query | Narrows the results with filter conditions. | | 3 | dataPoints, languageId, currencyId | Chooses what to return for each match. | | 4 | sort | Sets the order of the results. | | 5 | pagination | Sets the page size and moves between pages. | ## [Step 1: Define the Scope](#step-1-define-the-scope) The `scope` sets the starting universe of investments, limited to your entitled universe. A request must include a scope. For equities, the scope is defined with the exchange code data point. ```json "scope": { "shareClassInformation.exchangeCode": "XPAR" } ``` The scope is written in the same way as a query. You can pass a list of values to include several exchanges, or use a compound filter. If you use a compound filter, each branch must contain the exchange code data point. See [Compound Filters](https://developer-beta.morningstar.com/equities-screener-api/compound-filters). ## [Step 2: Build Filter Conditions](#step-2-build-filter-conditions) The `query` narrows the scoped universe with filter conditions. If you omit it, the screen returns everything in the scope. A single condition names a data point and a value. ```json "query": { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] } ``` To combine conditions, use `and`, `or` and `not`. The following query returns securities of the given types with a market capital date after 1 January 2024. ```json "query": { "and": [ { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] }, { "marketCapital.asOfDate": { "gt": "2024-01-01" } } ] } ``` Before you use a data point in a filter, check its metadata to confirm that it supports the operator you want. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points). Filter conditions are the most important and most complex part of a request. For all the filter types, syntax and rules, see [Filter Conditions](https://developer-beta.morningstar.com/equities-screener-api/filter-conditions). ## [Step 3: Select Data Points](#step-3-select-data-points) The `dataPoints` array lists the data points to return for each match. This keeps responses small, because you only receive what you ask for. - Each entry must be a valid data point name. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points). - A request can include up to 100 data points. - The performance ID is always returned. If you omit `dataPoints`, the performance ID is the only data point returned. ```json "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentName", "shareClassInformation.securityType", "marketCapital.asOfDate", "trailingReturn.trailing10YearReturn" ] ``` If a data point name isn't valid, the request fails with an error that lists the invalid names. See [Errors](https://developer-beta.morningstar.com/equities-screener-api/error-messages). ### [Set the Language and Currency](#set-the-language-and-currency) Some data points depend on a language or a currency. The metadata for each data point shows which ones do. | Property | Use | Default | | :--------- | :------------------------------------------------------------------------------- | :------ | | languageId | Required to retrieve language-dependent data points. Accepts a language code such as ENG, FRE or JPN. | ENG | | currencyId | Required to retrieve currency-dependent data points. Accepts an ISO 4217 currency code. | USD | For the full list of language codes, see [API Inputs](https://developer-beta.morningstar.com/equities-screener-api/api-inputs). In the example above, `trailingReturn.trailing10YearReturn` is currency-dependent, so the request should include a `currencyId`. ```json "currencyId": "EUR" ``` ## [Step 4: Set Sort Preferences](#step-4-set-sort-preferences) The `sort` array sets the order of the results. Each entry names a data point and a direction, `asc` or `desc`. - Entries are applied in order. - The data point must be sortable, and must also be in the `dataPoints` array. - If you don't set a sort order, results are in ascending performance ID order. ```json "sort": [ { "dataPoint": "marketCapital.asOfDate", "orderBy": "desc" } ] ``` ## [Step 5: Paginate Results](#step-5-paginate-results) Results are returned in pages. The `pagination` object sets the page size and moves you between pages. | Property | Description | | :---------------------- | :----------------------------------------------------------------- | | pageSize | The number of results per page. The default and maximum is 50. | | paginationTokenNext | The token for the next page, taken from the previous response. | | paginationTokenPrevious | The token for the previous page, taken from the previous response. | To page through the results: 1. Send the first request without a token. Set `pageSize` if you want fewer than 50 results per page. 2. Read `metadata.totalCount` for the total number of matches, and `metadata.paginationTokenNext` for the next page token. 3. Send the same request again with the token in `pagination.paginationTokenNext`. 4. Repeat until you have all the results. ```json "pagination": { "pageSize": 25, "paginationTokenNext": "{token from the previous response}" } ``` Use either the next token or the previous token in a request, not both. For how to read the tokens in the response, see [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results). ## [Send the Request](#send-the-request) The following request combines all five steps. ```bash curl --request POST \ --url "https://www.us-api.morningstar.com/direct-web-services/v1/screeners/equities" \ --header "Authorization: Bearer {token}" \ --header "Content-Type: application/json" \ --data '{ "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "and": [ { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] }, { "marketCapital.asOfDate": { "gt": "2024-01-01" } } ] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentName", "shareClassInformation.securityType", "marketCapital.asOfDate", "trailingReturn.trailing10YearReturn" ], "sort": [ { "dataPoint": "marketCapital.asOfDate", "orderBy": "desc" } ], "pagination": { "pageSize": 25 }, "currencyId": "EUR" }' ``` The response contains the matching investments and metadata, including any warnings. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results). For more complete requests, see [Example Screens](https://developer-beta.morningstar.com/equities-screener-api/example-screens). ## [Request Limits](#request-limits) - A request can include a maximum of **100 data points**. - A page contains a maximum of **50 results**. Use pagination to retrieve more. ## [Next Steps](#next-steps) - [Filter Conditions](https://developer-beta.morningstar.com/equities-screener-api/filter-conditions) covers every filter type in detail. - [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results) explains how to read the response and handle warnings. - [Example Screens](https://developer-beta.morningstar.com/equities-screener-api/example-screens) has complete requests you can adapt.