--- title: "Patch Screener" method: PATCH path: "/v1/saved-screeners/{screener_id}" tags: ["Screener"] --- # Patch Screener `PATCH /v1/saved-screeners/{screener_id}` ## Request - Base URL: `https://api.clearstreet.com` - URL: `https://api.clearstreet.com/v1/saved-screeners/{screener_id}` - Auth: HTTP bearer Partially update a saved screener configuration. Every field is optional. Omitting a field, or sending it as `null`, leaves the stored value unchanged. Sending a field's empty value clears it: `columns: []` clears the stored columns, `sorts: []` clears the stored sort, and `filters: []` clears the stored filters. `name: ""` is rejected -- a screener's name cannot be cleared. `shared: false` sets it to `false`; it is a value, not a clear. Unknown fields are rejected with a 422. ## Path parameters - `screener_id` string, uuid, required ## Request body - PatchScreenerRequest: Request body for partially updating a saved screener configuration. Every field is optional. Omitting a field, or sending it as `null`, leaves the stored value unchanged. Sending a field's empty value clears it: `columns: []` clears the stored columns, `sorts: []` clears the stored sort, and `filters: []` clears the stored filters. `name` has no empty value that clears it -- `name: ""` is rejected. `shared` has no empty value either -- `shared: false` sets it to `false`, it does not clear anything. Unknown fields are rejected. - `columns` FieldRef[], nullable: Structured field references to include when running this screener. Omit or send `null` to leave unchanged; `[]` clears the stored columns. - `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. Omit or send `null` to leave unchanged; `[]` clears the stored filters. - `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. Omit or send `null` to leave unchanged. Cannot be set to an empty string. - `shared` boolean, nullable: Whether any user may fetch this screener by id. Omit or send `null` to leave unchanged. `false` is a value, not a clear. - `sorts` SortSpec[], nullable: Multi-field sort specifications. Omit or send `null` to leave unchanged; `[]` clears the stored sort. - `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 updated 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 - `404`: Screener not found - `422`: Malformed request payload - `500`: Internal server error ## Changes - **2026-10-16** `1bd9eddeffc8`: 1 info - endpoint added [Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/saved-screeners/:screener_id/patch.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)