## Search Screener

`v1.screener.search_screener(ScreenerSearchScreenerParams**kwargs)  -> ScreenerSearchScreenerResponse`

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

### Parameters

- `columns: Optional[Iterable[FieldRefParam]]`

  Subset of fields to include in the response.

  - `name: str`

    The field name.

  - `lookback: Optional[FieldLookback]`

    Optional historical lookback window.

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

    - `"QUARTER"`

    - `"TRAILING_TWELVE_MONTHS"`

  - `value_type: Optional[FieldType]`

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

    - `"DECIMAL"`

    - `"INTEGER"`

    - `"STRING"`

    - `"ANALYST_RATING"`

    - `"DATE"`

- `field_filter: Optional[Iterable[FieldRefParam]]`

  Deprecated: use `columns` instead. Ignored when `columns` is provided.

  - `name: str`

    The field name.

  - `lookback: Optional[FieldLookback]`

    Optional historical lookback window.

  - `period: Optional[FieldPeriod]`

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

  - `value_type: Optional[FieldType]`

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

- `filters: Optional[Iterable[SearchFilterParam]]`

  Filter conditions to apply.

  - `left: FieldRef`

    The field to filter on.

    - `name: str`

      The field name.

    - `lookback: Optional[FieldLookback]`

      Optional historical lookback window.

    - `period: Optional[FieldPeriod]`

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

    - `value_type: Optional[FieldType]`

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

  - `op: Optional[FilterOpSpec]`

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

    - `name: FilterOperator`

      The operator to apply.

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

      - `"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]]`

      - `float`

      - `str`

    - `variable: Optional[Variable]`

      A variable reference.

      - `name: str`

        The variable name.

      - `lookback: Optional[FieldLookback]`

        Optional historical lookback window.

      - `modifier: Optional[Modifier]`

        Optional arithmetic modifier.

        - `args: List[Union[float, str]]`

          - `float`

          - `str`

        - `name: ModifierOp`

          The modifier operation.

          - `"ADD"`

          - `"SUBTRACT"`

      - `period: Optional[FieldPeriod]`

        Optional reporting period.

- `page_size: Optional[int]`

  The number of items to return per page (only used when page_token is not provided)

- `page_token: Optional[Union[str, Base64FileInput, null]]`

  Token for retrieving the next page of results. Contains encoded pagination state (limit + offset).
  When provided, page_size is ignored.

- `sort_case_sensitive: Optional[bool]`

  Whether string sorts should be case-sensitive (default: false).

- `sorts: Optional[Iterable[SortSpecParam]]`

  Multi-field sort specifications.

  - `field: FieldRef`

    The field to sort by.

  - `direction: Optional[SortDirection]`

    Sort direction (defaults to DESC).

    - `"ASC"`

    - `"DESC"`

### Returns

- `class ScreenerSearchScreenerResponse: …`

  - `data: ScreenerRowList`

    - `field: FieldRef`

      Field reference (same shape as filter/sort field references)

      - `name: str`

        The field name.

      - `lookback: Optional[FieldLookback]`

        Optional historical lookback window.

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

        - `"QUARTER"`

        - `"TRAILING_TWELVE_MONTHS"`

      - `value_type: Optional[FieldType]`

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

        - `"DECIMAL"`

        - `"INTEGER"`

        - `"STRING"`

        - `"ANALYST_RATING"`

        - `"DATE"`

    - `name: str`

      Human-readable display name for this field

    - `value: Union[float, str, null]`

      - `float`

      - `str`

    - `type: Optional[str]`

      Value format hint: "CURR_USD", "PERCENT", etc. Omitted when not applicable.
      When a null/undefined value is observed, it indicates it does not apply.

### Example

```python
from clearstreet import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.screener.search_screener()
print(response)
```

#### Response

```json
{
  "data": [
    [
      {
        "field": {
          "name": "symbol"
        },
        "name": "Symbol",
        "value": "AAPL"
      },
      {
        "field": {
          "name": "price"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": 175.05
      },
      {
        "field": {
          "name": "market_cap"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": 3500000000000
      },
      {
        "field": {
          "name": "beta"
        },
        "name": "Beta",
        "value": 1.2
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct"
        },
        "name": "Change (1W)",
        "type": "PERCENT",
        "value": 2.35
      },
      {
        "field": {
          "name": "consensus_rating"
        },
        "name": "Consensus Rating",
        "value": "STRONG_BUY"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER"
        },
        "name": "EPS (Q)",
        "type": "CURR_USD",
        "value": 1.55
      }
    ],
    [
      {
        "field": {
          "name": "symbol"
        },
        "name": "Symbol",
        "value": "F"
      },
      {
        "field": {
          "name": "price"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": 12.5
      },
      {
        "field": {
          "name": "market_cap"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": 45000000000
      },
      {
        "field": {
          "name": "beta"
        },
        "name": "Beta",
        "value": 1.5
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct"
        },
        "name": "Change (1W)",
        "type": "PERCENT",
        "value": -0.85
      },
      {
        "field": {
          "name": "consensus_rating"
        },
        "name": "Consensus Rating",
        "value": "HOLD"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER"
        },
        "name": "EPS (Q)",
        "type": "CURR_USD",
        "value": 0.23
      }
    ]
  ],
  "metadata": {
    "next_page_token": "AAAAAAAAAAoAAAAAAAAAAg",
    "request_id": "abc-123"
  }
}
```