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

Search Screener

v1.screener.search_screener(ScreenerSearchScreenerParams**kwargs) -> ScreenerSearchScreenerResponse
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
columns: Optional[Iterable[FieldRefParam]]

Subset of fields to include in the response.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

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

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
value_type: Optional[FieldType]

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

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
Deprecatedfield_filter: Optional[Iterable[FieldRefParam]]

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

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

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

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
value_type: Optional[FieldType]

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

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
filters: Optional[Iterable[SearchFilterParam]]

Filter conditions to apply.

left: FieldRef

The field to filter on.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

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

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
value_type: Optional[FieldType]

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

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
op: Optional[FilterOpSpec]

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

The operator to apply.

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

Optional arguments that modify operator behavior.

One of the following:
"LEFT_INCLUSIVE"
"RIGHT_INCLUSIVE"
"LEFT_EXCLUSIVE"
"RIGHT_EXCLUSIVE"
"CASE_INSENSITIVE"
right: Optional[List[FilterValue]]

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

value: Optional[Union[float, str, null]]
One of the following:
float
str
variable: Optional[Variable]

A variable reference.

name: str

The variable name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
modifier: Optional[Modifier]

Optional arithmetic modifier.

args: List[Union[float, str]]
One of the following:
float
str

The modifier operation.

One of the following:
"ADD"
"SUBTRACT"
period: Optional[FieldPeriod]

Optional reporting period.

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
page_size: Optional[int]

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

minimum0
page_token: Optional[Union[str, Base64FileInput, null]]

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

formatbyte
sort_case_sensitive: Optional[bool]

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

sorts: Optional[Iterable[SortSpecParam]]

Multi-field sort specifications.

field: FieldRef

The field to sort by.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

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

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
value_type: Optional[FieldType]

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

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
direction: Optional[SortDirection]

Sort direction (defaults to DESC).

One of the following:
"ASC"
"DESC"
ReturnsExpand Collapse
class ScreenerSearchScreenerResponse: …
field: FieldRef

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

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

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

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
value_type: Optional[FieldType]

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

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
name: str

Human-readable display name for this field

value: Union[float, str, null]
One of the following:
float
str
type: Optional[str]

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

from clearstreet import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.screener.search_screener()
print(response)
{
  "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"
  }
}