Skip to content
Clear Street Clear Street
Start Trading
API Reference
V1
Screener

Search Screener

ScreenerSearchScreenerResponse v1().screener().searchScreener(ScreenerSearchScreenerParamsparams = ScreenerSearchScreenerParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
POST/v1/screener

Search instruments using structured filters.

Returns a columnar response where each row is an array of column objects. Each column contains a human-readable name, a field reference, an optional type hint (e.g. CURR_USD, PERCENT), and the value.

Use columns to select which columns appear in each row. When omitted, the default field set is returned.

ParametersExpand Collapse
ScreenerSearchScreenerParams params
Optional<List<FieldRef>> columns

Subset of fields to include in the response.

String name

The field name.

Optional<FieldLookback> lookback

Optional historical lookback window.

One of the following:
ONE_DAY("ONE_DAY")
ONE_WEEK("ONE_WEEK")
ONE_MONTH("ONE_MONTH")
THREE_MONTHS("THREE_MONTHS")
SIX_MONTHS("SIX_MONTHS")
YEAR_TO_DATE("YEAR_TO_DATE")
ONE_YEAR("ONE_YEAR")
Optional<FieldPeriod> period

Optional reporting period (e.g. quarter or TTM).

One of the following:
QUARTER("QUARTER")
TRAILING_TWELVE_MONTHS("TRAILING_TWELVE_MONTHS")
Optional<FieldType> valueType

The data type of the field value. Present only in responses.

One of the following:
DECIMAL("DECIMAL")
INTEGER("INTEGER")
STRING("STRING")
ANALYST_RATING("ANALYST_RATING")
DATE("DATE")
DeprecatedOptional<List<FieldRef>> fieldFilter

Deprecated: use columns instead. Ignored when columns is provided.

String name

The field name.

Optional<FieldLookback> lookback

Optional historical lookback window.

One of the following:
ONE_DAY("ONE_DAY")
ONE_WEEK("ONE_WEEK")
ONE_MONTH("ONE_MONTH")
THREE_MONTHS("THREE_MONTHS")
SIX_MONTHS("SIX_MONTHS")
YEAR_TO_DATE("YEAR_TO_DATE")
ONE_YEAR("ONE_YEAR")
Optional<FieldPeriod> period

Optional reporting period (e.g. quarter or TTM).

One of the following:
QUARTER("QUARTER")
TRAILING_TWELVE_MONTHS("TRAILING_TWELVE_MONTHS")
Optional<FieldType> valueType

The data type of the field value. Present only in responses.

One of the following:
DECIMAL("DECIMAL")
INTEGER("INTEGER")
STRING("STRING")
ANALYST_RATING("ANALYST_RATING")
DATE("DATE")
Optional<List<SearchFilter>> filters

Filter conditions to apply.

The field to filter on.

String name

The field name.

Optional<FieldLookback> lookback

Optional historical lookback window.

One of the following:
ONE_DAY("ONE_DAY")
ONE_WEEK("ONE_WEEK")
ONE_MONTH("ONE_MONTH")
THREE_MONTHS("THREE_MONTHS")
SIX_MONTHS("SIX_MONTHS")
YEAR_TO_DATE("YEAR_TO_DATE")
ONE_YEAR("ONE_YEAR")
Optional<FieldPeriod> period

Optional reporting period (e.g. quarter or TTM).

One of the following:
QUARTER("QUARTER")
TRAILING_TWELVE_MONTHS("TRAILING_TWELVE_MONTHS")
Optional<FieldType> valueType

The data type of the field value. Present only in responses.

One of the following:
DECIMAL("DECIMAL")
INTEGER("INTEGER")
STRING("STRING")
ANALYST_RATING("ANALYST_RATING")
DATE("DATE")
Optional<FilterOpSpec> op

The operator and optional arguments. Omit together with right for an unenabled filter.

The operator to apply.

One of the following:
LESS_THAN("LESS_THAN")
LESS_OR_EQUAL("LESS_OR_EQUAL")
GREATER_THAN("GREATER_THAN")
GREATER_OR_EQUAL("GREATER_OR_EQUAL")
EQUAL("EQUAL")
BETWEEN("BETWEEN")
NOT_BETWEEN("NOT_BETWEEN")
ONE_OF("ONE_OF")
REGEX("REGEX")
BEGINS_WITH("BEGINS_WITH")
ENDS_WITH("ENDS_WITH")
CONTAINS("CONTAINS")
IS_NULL("IS_NULL")
IS_NOT_NULL("IS_NOT_NULL")
Optional<List<OperatorArg>> args

Optional arguments that modify operator behavior.

One of the following:
LEFT_INCLUSIVE("LEFT_INCLUSIVE")
RIGHT_INCLUSIVE("RIGHT_INCLUSIVE")
LEFT_EXCLUSIVE("LEFT_EXCLUSIVE")
RIGHT_EXCLUSIVE("RIGHT_EXCLUSIVE")
CASE_INSENSITIVE("CASE_INSENSITIVE")
Optional<List<FilterValue>> right

The value(s) to compare against. Omit together with op for an unenabled filter.

Optional<Value> value
One of the following:
double
String
Optional<Variable> variable

A variable reference.

String name

The variable name.

Optional<FieldLookback> lookback

Optional historical lookback window.

One of the following:
ONE_DAY("ONE_DAY")
ONE_WEEK("ONE_WEEK")
ONE_MONTH("ONE_MONTH")
THREE_MONTHS("THREE_MONTHS")
SIX_MONTHS("SIX_MONTHS")
YEAR_TO_DATE("YEAR_TO_DATE")
ONE_YEAR("ONE_YEAR")
Optional<Modifier> modifier

Optional arithmetic modifier.

List<Arg> args
One of the following:
double
String

The modifier operation.

One of the following:
ADD("ADD")
SUBTRACT("SUBTRACT")
Optional<FieldPeriod> period

Optional reporting period.

One of the following:
QUARTER("QUARTER")
TRAILING_TWELVE_MONTHS("TRAILING_TWELVE_MONTHS")
Optional<Long> pageSize

The number of items to return per page (only used when page_token is not provided)

minimum0
Optional<String> pageToken

Token for retrieving the next page of results. Contains encoded pagination state (limit + offset). When provided, page_size is ignored.

formatbyte
Optional<Boolean> sortCaseSensitive

Whether string sorts should be case-sensitive (default: false).

Optional<List<SortSpec>> sorts

Multi-field sort specifications.

FieldRef field

The field to sort by.

String name

The field name.

Optional<FieldLookback> lookback

Optional historical lookback window.

One of the following:
ONE_DAY("ONE_DAY")
ONE_WEEK("ONE_WEEK")
ONE_MONTH("ONE_MONTH")
THREE_MONTHS("THREE_MONTHS")
SIX_MONTHS("SIX_MONTHS")
YEAR_TO_DATE("YEAR_TO_DATE")
ONE_YEAR("ONE_YEAR")
Optional<FieldPeriod> period

Optional reporting period (e.g. quarter or TTM).

One of the following:
QUARTER("QUARTER")
TRAILING_TWELVE_MONTHS("TRAILING_TWELVE_MONTHS")
Optional<FieldType> valueType

The data type of the field value. Present only in responses.

One of the following:
DECIMAL("DECIMAL")
INTEGER("INTEGER")
STRING("STRING")
ANALYST_RATING("ANALYST_RATING")
DATE("DATE")
Optional<SortDirection> direction

Sort direction (defaults to DESC).

One of the following:
ASC("ASC")
DESC("DESC")
ReturnsExpand Collapse
class ScreenerSearchScreenerResponse:
List<List<ScreenerColumn>> data
FieldRef field

Field reference (same shape as filter/sort field references)

String name

The field name.

Optional<FieldLookback> lookback

Optional historical lookback window.

One of the following:
ONE_DAY("ONE_DAY")
ONE_WEEK("ONE_WEEK")
ONE_MONTH("ONE_MONTH")
THREE_MONTHS("THREE_MONTHS")
SIX_MONTHS("SIX_MONTHS")
YEAR_TO_DATE("YEAR_TO_DATE")
ONE_YEAR("ONE_YEAR")
Optional<FieldPeriod> period

Optional reporting period (e.g. quarter or TTM).

One of the following:
QUARTER("QUARTER")
TRAILING_TWELVE_MONTHS("TRAILING_TWELVE_MONTHS")
Optional<FieldType> valueType

The data type of the field value. Present only in responses.

One of the following:
DECIMAL("DECIMAL")
INTEGER("INTEGER")
STRING("STRING")
ANALYST_RATING("ANALYST_RATING")
DATE("DATE")
String name

Human-readable display name for this field

Optional<Value> value
One of the following:
double
String
Optional<String> type

Value format hint: “CURR_USD”, “PERCENT”, etc. Omitted when not applicable. When a null/undefined value is observed, it indicates it does not apply.

Search Screener

package com.clearstreet.api.example;

import com.clearstreet.api.client.ClearStreetClient;
import com.clearstreet.api.client.okhttp.ClearStreetOkHttpClient;
import com.clearstreet.api.models.v1.screener.ScreenerSearchScreenerParams;
import com.clearstreet.api.models.v1.screener.ScreenerSearchScreenerResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        ClearStreetClient client = ClearStreetOkHttpClient.builder()
            .fromEnv()
            .apiKey("My API Key")
            .build();

        ScreenerSearchScreenerResponse response = client.v1().screener().searchScreener();
    }
}
{
  "data": [
    [
      {
        "field": {
          "name": "symbol"
        },
        "name": "Symbol",
        "value": "AAPL"
      },
      {
        "field": {
          "name": "price"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": 175.05
      },
      {
        "field": {
          "name": "market_cap"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": 3500000000000
      },
      {
        "field": {
          "name": "beta"
        },
        "name": "Beta",
        "value": 1.2
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct"
        },
        "name": "Change (1W)",
        "type": "PERCENT",
        "value": 2.35
      },
      {
        "field": {
          "name": "consensus_rating"
        },
        "name": "Consensus Rating",
        "value": "STRONG_BUY"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER"
        },
        "name": "EPS (Q)",
        "type": "CURR_USD",
        "value": 1.55
      }
    ],
    [
      {
        "field": {
          "name": "symbol"
        },
        "name": "Symbol",
        "value": "F"
      },
      {
        "field": {
          "name": "price"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": 12.5
      },
      {
        "field": {
          "name": "market_cap"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": 45000000000
      },
      {
        "field": {
          "name": "beta"
        },
        "name": "Beta",
        "value": 1.5
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct"
        },
        "name": "Change (1W)",
        "type": "PERCENT",
        "value": -0.85
      },
      {
        "field": {
          "name": "consensus_rating"
        },
        "name": "Consensus Rating",
        "value": "HOLD"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER"
        },
        "name": "EPS (Q)",
        "type": "CURR_USD",
        "value": 0.23
      }
    ]
  ],
  "metadata": {
    "next_page_token": "AAAAAAAAAAoAAAAAAAAAAg",
    "request_id": "abc-123"
  }
}
{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: unknown field `sort_by` at line 3 column 18"
  },
  "metadata": {
    "request_id": "69f02ce8-20e3-4bcd-a134-bb006eca5749"
  }
}
Returns Examples
{
  "data": [
    [
      {
        "field": {
          "name": "symbol"
        },
        "name": "Symbol",
        "value": "AAPL"
      },
      {
        "field": {
          "name": "price"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": 175.05
      },
      {
        "field": {
          "name": "market_cap"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": 3500000000000
      },
      {
        "field": {
          "name": "beta"
        },
        "name": "Beta",
        "value": 1.2
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct"
        },
        "name": "Change (1W)",
        "type": "PERCENT",
        "value": 2.35
      },
      {
        "field": {
          "name": "consensus_rating"
        },
        "name": "Consensus Rating",
        "value": "STRONG_BUY"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER"
        },
        "name": "EPS (Q)",
        "type": "CURR_USD",
        "value": 1.55
      }
    ],
    [
      {
        "field": {
          "name": "symbol"
        },
        "name": "Symbol",
        "value": "F"
      },
      {
        "field": {
          "name": "price"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": 12.5
      },
      {
        "field": {
          "name": "market_cap"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": 45000000000
      },
      {
        "field": {
          "name": "beta"
        },
        "name": "Beta",
        "value": 1.5
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct"
        },
        "name": "Change (1W)",
        "type": "PERCENT",
        "value": -0.85
      },
      {
        "field": {
          "name": "consensus_rating"
        },
        "name": "Consensus Rating",
        "value": "HOLD"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER"
        },
        "name": "EPS (Q)",
        "type": "CURR_USD",
        "value": 0.23
      }
    ]
  ],
  "metadata": {
    "next_page_token": "AAAAAAAAAAoAAAAAAAAAAg",
    "request_id": "abc-123"
  }
}
{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: unknown field `sort_by` at line 3 column 18"
  },
  "metadata": {
    "request_id": "69f02ce8-20e3-4bcd-a134-bb006eca5749"
  }
}