--- title: "Create Screener" method: POST path: "/v1/saved-screeners" tags: ["Screener"] --- # Create Screener `POST /v1/saved-screeners` ## Request - Base URL: `https://api.clearstreet.com` - URL: `https://api.clearstreet.com/v1/saved-screeners` - Auth: HTTP bearer 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 - `shared` boolean, nullable: Whether any user may fetch this screener by id. Omit to leave the existing value unchanged (defaults to `false` when creating). - `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 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 - `shared` boolean, required: Whether any user may fetch this screener by id. - `sorts` SortSpec[], nullable - `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. - `updated_at` string, date-time, required ## Other responses - `400`: Invalid request - `500`: Internal server error ## Changes - **2026-10-16** `1bd9eddeffc8`: 2 info - added the new optional request property `shared` - added the required property `allOf[subschema #2]/data/shared` to the response with the `200` status - **2026-07-15** `169e8b9ad50c`: 4 warning, 4 info - added the new `ANNUAL` enum value to the `allOf[subschema #2]/data/columns/items/period/oneOf[#/components/schemas/FieldPeriod]/` response property for the response status `200` - added the new `ANNUAL` enum value to the `allOf[subschema #2]/data/filters/items/left/period/oneOf[#/components/schemas/FieldPeriod]/` response property for the response status `200` - added the new `ANNUAL` enum value to the `allOf[subschema #2]/data/filters/items/right/items/variable/oneOf[#/components/schemas/Variable]/period/oneOf[#/components/schemas/FieldPeriod]/` response property for the response status `200` - added the new `ANNUAL` enum value to the `allOf[subschema #2]/data/sorts/items/field/period/oneOf[#/components/schemas/FieldPeriod]/` response property for the response status `200` - …4 more - **2026-06-29** `494ac4441461`: 2 warning - removed the request property `field_filter` - removed the optional property `allOf[subschema #2]/data/field_filter` from the response with the `200` status - **2026-06-17** `3484367a80f8`: 1 info - endpoint added [Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/saved-screeners/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)