---
title: "Search Screener"
method: POST
path: "/v1/screener"
tags: ["Screener"]
---

# Search Screener

`POST /v1/screener`

## Request

- Base URL: `https://api.clearstreet.com`
- URL: `https://api.clearstreet.com/v1/screener`
- Auth: HTTP bearer

Search instruments using structured filters.

Compose a request with `filters`, plus optional `sorts`, `columns`, and
`page_size`/`page_token` for pagination. Each filter pairs a field reference
(`left`) with an operator (`op`, e.g. `GREATER_OR_EQUAL`, `BETWEEN`) and
comparison values (`right`), which can be literals or date variables such as
`today` with a modifier. Field names, periods, and lookbacks come from the
screener field catalog. `sorts` order results; `columns` selects which
fields appear in each row (the default field set when omitted).

The response is a paginated, columnar list of matching instruments. Each row
is an array of column objects, each with a display `name`, the `field`
reference, an optional value `type` hint (e.g. `CURR_USD`, `PERCENT`), and
the `value`. An `instrument_id` column is always prepended. Metadata carries
`total_items`, `total_pages`, and `next_page_token` for paging.

Screener results can shuffle between calls; reconcile by re-checking rows
across pages rather than assuming stable ordering.

## Request body

- ScreenerSearchRequest: Request body for POST /screener.
  - `page_size` integer, nullable: The number of items to return per page (only used when page_token is not provided)
  - `page_token` string, byte: Base64URL-encoded pagination token
  - `columns` FieldRef[], nullable: Subset of fields to include in the response.
    - `lookback` 'ONE_DAY' | 'ONE_WEEK' | 'ONE_MONTH' | 'THREE_MONTHS' | 'SIX_MONTHS' | 'YEAR_TO_DATE' | 'ONE_YEAR': Historical lookback window for price/change fields.
    - `name` string, required: The field name.
    - `period` 'QUARTER' | 'TRAILING_TWELVE_MONTHS' | 'ANNUAL': Reporting period for financial data fields.
    - `value_type` 'DECIMAL' | 'INTEGER' | 'STRING' | 'ANALYST_RATING' | 'DATE': The data type of a screener field value.
  - `filters` SearchFilter[], nullable: Filter conditions to apply.
    - `left` FieldRef, required: A reference to a screener field.
      - `lookback` 'ONE_DAY' | 'ONE_WEEK' | 'ONE_MONTH' | 'THREE_MONTHS' | 'SIX_MONTHS' | 'YEAR_TO_DATE' | 'ONE_YEAR': Historical lookback window for price/change fields.
      - `name` string, required: The field name.
      - `period` 'QUARTER' | 'TRAILING_TWELVE_MONTHS' | 'ANNUAL': Reporting period for financial data fields.
      - `value_type` 'DECIMAL' | 'INTEGER' | 'STRING' | 'ANALYST_RATING' | 'DATE': The data type of a screener field value.
    - `op` FilterOpSpec: Operator specification with optional behavioral arguments.
      - `args` OperatorArg[]: Optional arguments that modify operator behavior.
      - `name` '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', required: Filter operators supported by the screener. Abbreviated and lowercase forms are accepted as serde aliases for backward compatibility with earlier API revisions; the canonical wire form is the SCREAMING_SNAKE_CASE rendering.
    - `right` FilterValue[], nullable: The value(s) to compare against. Omit together with `op` for an unenabled filter.
      - `value` union
        - number
        - string
      - `variable` Variable: A variable reference (field or built-in like `today`).
        - `lookback` 'ONE_DAY' | 'ONE_WEEK' | 'ONE_MONTH' | 'THREE_MONTHS' | 'SIX_MONTHS' | 'YEAR_TO_DATE' | 'ONE_YEAR': Historical lookback window for price/change fields.
        - `modifier` Modifier: Arithmetic modifier applied to a variable value.
          - `args` union[], required
            - union
              - …
          - `name` 'ADD' | 'SUBTRACT', required: Modifier operation applied to a variable.
        - `name` string, required: The variable name.
        - `period` 'QUARTER' | 'TRAILING_TWELVE_MONTHS' | 'ANNUAL': Reporting period for financial data fields.
  - `sort_case_sensitive` boolean, nullable: Whether string sorts should be case-sensitive (default: false).
  - `sorts` SortSpec[], nullable: Multi-field sort specifications.
    - `direction` 'ASC' | 'DESC': Sort direction for sorted results
    - `field` FieldRef, required: A reference to a screener field.
      - `lookback` 'ONE_DAY' | 'ONE_WEEK' | 'ONE_MONTH' | 'THREE_MONTHS' | 'SIX_MONTHS' | 'YEAR_TO_DATE' | 'ONE_YEAR': Historical lookback window for price/change fields.
      - `name` string, required: The field name.
      - `period` 'QUARTER' | 'TRAILING_TWELVE_MONTHS' | 'ANNUAL': Reporting period for financial data fields.
      - `value_type` 'DECIMAL' | 'INTEGER' | 'STRING' | 'ANALYST_RATING' | 'DATE': The data type of a screener field value.

## Response `200`

Screener results

- object
  - `error` ApiError: A direct mapping of tonic::Status, for use in HTTP responses.
    - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code.
    - `details` object[]
    - `message` string, required: A human-readable message providing more details about the error.
  - `metadata` ResponseMetadata, required: Metadata for the response. This will always contain a request ID which can be used to identify the request to Clear Street for tracing, and optionally may include pagination data.
    - `next_page_token` string, byte, nullable: Base64URL-encoded pagination token
    - `page_number` integer, nullable: Pagination. Included if this was a GET (list) response
    - `previous_page_token` string, byte, nullable: Base64URL-encoded pagination token
    - `request_id` string, required: A unique ID for this request, generated upon ingestion of the request.
    - `total_items` integer, nullable: Total number of items available (not just in this page).
    - `total_pages` integer, nullable: Total number of pages available.
  - `data` ScreenerRow[], required
    - ScreenerColumn[]: A single row of screener columns for one instrument.
      - `field` FieldRef, required: A reference to a screener field.
        - `lookback` 'ONE_DAY' | 'ONE_WEEK' | 'ONE_MONTH' | 'THREE_MONTHS' | 'SIX_MONTHS' | 'YEAR_TO_DATE' | 'ONE_YEAR': Historical lookback window for price/change fields.
        - `name` string, required: The field name.
        - `period` 'QUARTER' | 'TRAILING_TWELVE_MONTHS' | 'ANNUAL': Reporting period for financial data fields.
        - `value_type` 'DECIMAL' | 'INTEGER' | 'STRING' | 'ANALYST_RATING' | 'DATE': The data type of a screener field value.
      - `name` string, required: Human-readable display name for this field
      - `type` string, nullable: Value format hint: "CURR_USD", "PERCENT", etc. Omitted when not applicable. When a null/undefined value is observed, it indicates it does not apply.
      - `value` union, required
        - number
        - string

## Other responses

- `400`: Invalid request
- `422`: Malformed request payload
- `500`: Internal server error

## Changes

- **2026-10-16** `1bd9eddeffc8`: 1 breaking
  - the `allOf[#/components/schemas/PaginationParams]/page_size` request property's min was increased to `1.00`
- **2026-07-15** `169e8b9ad50c`: 1 warning, 4 info
  - added the new `ANNUAL` enum value to the `allOf[subschema #2]/data/items/items/field/period/oneOf[#/components/schemas/FieldPeriod]/` response property for the response status `200`
  - added the new `ANNUAL` enum value to the request property `allOf[subschema #2]/columns/items/period/oneOf[#/components/schemas/FieldPeriod]/`
  - added the new `ANNUAL` enum value to the request property `allOf[subschema #2]/filters/items/left/period/oneOf[#/components/schemas/FieldPeriod]/`
  - added the new `ANNUAL` enum value to the request property `allOf[subschema #2]/filters/items/right/items/variable/oneOf[#/components/schemas/Variable]/period/oneOf[#/components/schemas/FieldPeriod]/`
  - …1 more
- **2026-06-29** `494ac4441461`: 1 warning
  - removed the request property `allOf[subschema #2]/field_filter`
- **2026-06-17** `3484367a80f8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/screener/post.md)

---

[API](https://skmtc.dev/clear-street/apis/clear-street-trading-api.md) - [All operations](https://skmtc.dev/clear-street/apis/clear-street-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clear-street/apis/clear-street-trading-api/revisions/52e77ea7d731?raw)