---
title: "Create Screener"
method: POST
path: "/v1/saved-screeners"
tags: ["Screener"]
---

# Create Screener

`POST /v1/saved-screeners`

Create a saved screener configuration.

Persists a screener configuration for the authenticated user.

## Request body

- CreateScreenerRequest — Request body for creating or updating a saved screener configuration
  - `columns` FieldRef[], nullable — Structured field references to include when running this screener
    - `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 — Structured search filter criteria
    - `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.
  - `name` string, nullable — The name for this screener configuration
  - `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 created successfully

- 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` ScreenerEntry, required — A saved screener configuration entry
    - `columns` FieldRef[], nullable — Field references included when running this screener.
      - `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.
    - `created_at` string, date-time, required
    - `filters` SearchFilter[], required
      - `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
              - …
            - `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.
    - `id` string, uuid, required
    - `name` string, required
    - `sorts` SortSpec[], nullable
      - `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.
    - `updated_at` string, date-time, required

## Other responses

- `400` — Invalid request
- `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/versions/80e6fb2644e0/schema)