Core Concepts

The Equities Screener API finds equities that match criteria you define and returns the data you choose for each match. This page explains the terms used throughout the guide, so that requests and responses are easier to build and read.

How a Screen Works

A screen is a single request that describes what to look for and what to return. The API handles it in this order.

1. It starts from your entitled universe of equities.
2. It applies the scope, which sets the starting universe for the screen.
3. It applies the query, which narrows the universe with filter conditions.
4. It returns the data points you selected for each match, sorted and divided into pages.

A request is made up of the following properties.

The API has two endpoints. One lists the data points that you can use, with their metadata. The other runs a screen. Use the first to find out what you can filter on, sort by and return, and the second to build the screen.

Entitled Universe

Every screen runs against the equities you are entitled to. A screen can never return an investment outside your entitled universe, whatever its scope and query say.

Entitlements also apply to data points. If you request a data point that you aren't entitled to for a particular investment, the investment is still returned, and a warning in the response lists the data points that couldn't be returned. See Results.

Data Points

A data point is a named value for an equity, such as a symbol, a market capital date or a trailing return. Data point names have the format <dataGroup>.<fieldName>, for example shareClassInformation.symbol and marketCapital.asOfDate.

You use data points in three ways:

• To filter. A filter condition applies to a data point.
• To return. The dataPoints array lists the data points to include in the results.
• To sort. The sort array orders results by a data point. The data point must also be in the dataPoints array.

Data Point Metadata

The API describes each data point with metadata, which tells you how it can be used.

Data Types

The data type determines which filters apply.

For how to find data points and read their metadata, see Explore Data Points.

Scope

The scope defines the starting universe of investments, limited to your entitled universe. For equities, it is defined with the exchange code data point.

"scope": {
  "shareClassInformation.exchangeCode": "XPAR"
}

scope is written in the same way as a query, so it can use compound filters. If it does, each branch must contain the scoping data point.

Query and Filter Conditions

The query narrows the scoped universe. It is made up of filter conditions, each of which applies to one data point. The conditions fall into three kinds.

A single condition names a data point and a value.

"query": {
  "shareClassInformation.symbol": "MSES"
}

A compound condition combines several conditions, here requiring both a symbol match and a date range.

"query": {
  "and": [
    { "shareClassInformation.symbol": ["MSES", "CA40"] },
    { "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-01-01" } }
  ]
}

Filter conditions are the most important and most complex part of a request, so they have their own section. See Filter Conditions.

Languages and Currencies

Some data points depend on a language or a currency. For example, a data point that returns text in the language of your choice is language-dependent, and one that returns a monetary value is currency-dependent.

• Pass languageId to request language-dependent data points. The default is ENG.
• Pass currencyId to request currency-dependent data points, using an ISO 4217 currency code. The default is USD.

The metadata for each data point shows whether it has either dependency.

Sorting and Pagination

Sorting. 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, so later ones break ties in earlier ones. If you don't set a sort order, results are in ascending performance ID order.

Pagination. Results are returned in pages. The default and maximum page size is 50. The response includes tokens for the next and previous pages, which you pass back in the pagination object to move between pages. Use one token in a request, not both.

Results

A screen returns two things: the matching investments and metadata about the response.

{
  "investments": [
    {
      "instrumentIdentifiers.performanceId": "0P0001VK71",
      "shareClassInformation.symbol": "MSES",
      "shareClassInformation.investmentStatus": 1
    }
  ],
  "metadata": {
    "totalCount": 1,
    "messages": [
      {
        "investments": [
          {
            "status": "Data points are not entitled for 0P0001VK71 security",
            "dataPoints": ["quantitativeFairValues.quantitativeMoat"],
            "errorCode": "403",
            "id": "0P0001VK71"
          }
        ],
        "type": "Warning"
      }
    ],
    "requestId": "092fa93b-d63d-4b6e-a53b-d7ace50473ff",
    "time": "2025-10-03T17:48:16.0302555Z"
  }
}

• Investments. Each match is a flat object. Its keys are data point names, and its values are strings, numbers, integers or booleans, and can be null. The performance ID is included in every match.
• totalCount. The total number of matches found, across all pages.
• Pagination tokens. The tokens for retrieving the next and previous pages.
• messages. Warnings about the response, such as data points that aren't entitled. A 200 response doesn't guarantee that every data point was returned for every investment, so check messages every time.
• requestId and time. The identifier of the request and the time the response was returned. Include the requestId if you contact support.

For details, see Work with Results.

Next Steps

• Explore Data Points to find the data points and operators you can use.
• Screen Equities to build a complete request.
• Filter Conditions for the syntax and rules of filters.
• Work with Results to read the response.