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

# Search Screener

`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.

## 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 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

---

[API](https://skmtc.net/clear-street/apis/clear-street-trading-api.md) · [All operations](https://skmtc.net/clear-street/apis/clear-street-trading-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clear-street/clear-street-trading-api/revisions/80e6fb2644e0/schema)