Skip to content
Clear Street Clear Street Clear Street
Start Trading
API Reference
V1
Screener

Patch Screener

v1.screener.patch_screener(strscreener_id, ScreenerPatchScreenerParams**kwargs) -> ScreenerPatchScreenerResponse
PATCH/v1/saved-screeners/{screener_id}

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.

ParametersExpand Collapse
screener_id: str
columns: Optional[Iterable[FieldRefParam]]

Structured field references to include when running this screener. Omit or send null to leave unchanged; [] clears the stored columns.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

Optional reporting period (e.g. quarter or TTM).

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
value_type: Optional[FieldType]

The data type of the field value. Present only in responses.

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
filters: Optional[Iterable[SearchFilterParam]]

Structured search filter criteria. Omit or send null to leave unchanged; [] clears the stored filters.

left: FieldRef

The field to filter on.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

Optional reporting period (e.g. quarter or TTM).

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
value_type: Optional[FieldType]

The data type of the field value. Present only in responses.

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
op: Optional[FilterOpSpec]

The operator and optional arguments. Omit together with right for an unenabled filter.

The operator to apply.

One of the following:
"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"
args: Optional[List[OperatorArg]]

Optional arguments that modify operator behavior.

One of the following:
"LEFT_INCLUSIVE"
"RIGHT_INCLUSIVE"
"LEFT_EXCLUSIVE"
"RIGHT_EXCLUSIVE"
"CASE_INSENSITIVE"
right: Optional[List[FilterValue]]

The value(s) to compare against. Omit together with op for an unenabled filter.

value: Optional[Union[float, str, null]]
One of the following:
float
str
variable: Optional[Variable]

A variable reference.

name: str

The variable name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
modifier: Optional[Modifier]

Optional arithmetic modifier.

args: List[Union[float, str]]
One of the following:
float
str

The modifier operation.

One of the following:
"ADD"
"SUBTRACT"
period: Optional[FieldPeriod]

Optional reporting period.

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
name: Optional[str]

The name for this screener configuration. Omit or send null to leave unchanged. Cannot be set to an empty string.

shared: Optional[bool]

Whether any user may fetch this screener by id. Omit or send null to leave unchanged. false is a value, not a clear.

sorts: Optional[Iterable[SortSpecParam]]

Multi-field sort specifications. Omit or send null to leave unchanged; [] clears the stored sort.

field: FieldRef

The field to sort by.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

Optional reporting period (e.g. quarter or TTM).

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
value_type: Optional[FieldType]

The data type of the field value. Present only in responses.

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
direction: Optional[SortDirection]

Sort direction (defaults to DESC).

One of the following:
"ASC"
"DESC"
ReturnsExpand Collapse
class ScreenerPatchScreenerResponse: …

A saved screener configuration entry

id: str
created_at: datetime
filters: List[SearchFilter]
left: FieldRef

The field to filter on.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

Optional reporting period (e.g. quarter or TTM).

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
value_type: Optional[FieldType]

The data type of the field value. Present only in responses.

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
op: Optional[FilterOpSpec]

The operator and optional arguments. Omit together with right for an unenabled filter.

The operator to apply.

One of the following:
"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"
args: Optional[List[OperatorArg]]

Optional arguments that modify operator behavior.

One of the following:
"LEFT_INCLUSIVE"
"RIGHT_INCLUSIVE"
"LEFT_EXCLUSIVE"
"RIGHT_EXCLUSIVE"
"CASE_INSENSITIVE"
right: Optional[List[FilterValue]]

The value(s) to compare against. Omit together with op for an unenabled filter.

value: Optional[Union[float, str, null]]
One of the following:
float
str
variable: Optional[Variable]

A variable reference.

name: str

The variable name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
modifier: Optional[Modifier]

Optional arithmetic modifier.

args: List[Union[float, str]]
One of the following:
float
str

The modifier operation.

One of the following:
"ADD"
"SUBTRACT"
period: Optional[FieldPeriod]

Optional reporting period.

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
name: str
shared: bool

Whether any user may fetch this screener by id.

updated_at: datetime
columns: Optional[List[FieldRef]]

Field references included when running this screener.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

Optional reporting period (e.g. quarter or TTM).

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
value_type: Optional[FieldType]

The data type of the field value. Present only in responses.

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
sorts: Optional[List[SortSpec]]
field: FieldRef

The field to sort by.

name: str

The field name.

lookback: Optional[FieldLookback]

Optional historical lookback window.

One of the following:
"ONE_DAY"
"ONE_WEEK"
"ONE_MONTH"
"THREE_MONTHS"
"SIX_MONTHS"
"YEAR_TO_DATE"
"ONE_YEAR"
period: Optional[FieldPeriod]

Optional reporting period (e.g. quarter or TTM).

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
"ANNUAL"
value_type: Optional[FieldType]

The data type of the field value. Present only in responses.

One of the following:
"DECIMAL"
"INTEGER"
"STRING"
"ANALYST_RATING"
"DATE"
direction: Optional[SortDirection]

Sort direction (defaults to DESC).

One of the following:
"ASC"
"DESC"

Patch Screener

from clearstreet import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.screener.patch_screener(
    screener_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
{
  "data": {
    "columns": [
      {
        "name": "symbol"
      },
      {
        "name": "price"
      },
      {
        "name": "market_cap"
      }
    ],
    "created_at": "2026-04-23T13:37:04.041398Z",
    "filters": [
      {
        "left": {
          "name": "market_cap"
        },
        "op": {
          "name": "GREATER_OR_EQUAL"
        },
        "right": [
          {
            "value": 1000000000
          }
        ]
      }
    ],
    "id": "69fcb40a-1812-4856-b2d3-97dec805efee",
    "name": "Tech Large Caps",
    "sorts": [
      {
        "direction": "ASC",
        "field": {
          "name": "market_cap"
        }
      }
    ],
    "updated_at": "2026-04-23T13:37:21.860106Z"
  },
  "metadata": {
    "request_id": "71ac58a8-9b12-49b9-8301-6239febe4e56"
  }
}
{
  "error": {
    "code": 400,
    "message": "name cannot be empty"
  },
  "metadata": {
    "request_id": "b8d191a9-0f76-4867-996e-4845ae01d864"
  }
}
{
  "error": {
    "code": 404,
    "message": "Some requested entity was not found"
  },
  "metadata": {
    "request_id": "2cf7b8b2-f4c7-4db5-a617-b45324352fb7"
  }
}
{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: unknown field `column`, expected one of `name`, `columns`, `filters`, `sorts`, `shared` at line 1 column 10"
  },
  "metadata": {
    "request_id": "6b0f4c3e-6f7f-49c7-9f1e-0b6a1c2d3e4f"
  }
}
Returns Examples
{
  "data": {
    "columns": [
      {
        "name": "symbol"
      },
      {
        "name": "price"
      },
      {
        "name": "market_cap"
      }
    ],
    "created_at": "2026-04-23T13:37:04.041398Z",
    "filters": [
      {
        "left": {
          "name": "market_cap"
        },
        "op": {
          "name": "GREATER_OR_EQUAL"
        },
        "right": [
          {
            "value": 1000000000
          }
        ]
      }
    ],
    "id": "69fcb40a-1812-4856-b2d3-97dec805efee",
    "name": "Tech Large Caps",
    "sorts": [
      {
        "direction": "ASC",
        "field": {
          "name": "market_cap"
        }
      }
    ],
    "updated_at": "2026-04-23T13:37:21.860106Z"
  },
  "metadata": {
    "request_id": "71ac58a8-9b12-49b9-8301-6239febe4e56"
  }
}
{
  "error": {
    "code": 400,
    "message": "name cannot be empty"
  },
  "metadata": {
    "request_id": "b8d191a9-0f76-4867-996e-4845ae01d864"
  }
}
{
  "error": {
    "code": 404,
    "message": "Some requested entity was not found"
  },
  "metadata": {
    "request_id": "2cf7b8b2-f4c7-4db5-a617-b45324352fb7"
  }
}
{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: unknown field `column`, expected one of `name`, `columns`, `filters`, `sorts`, `shared` at line 1 column 10"
  },
  "metadata": {
    "request_id": "6b0f4c3e-6f7f-49c7-9f1e-0b6a1c2d3e4f"
  }
}