Search Screener

$ clst v1:screener search-screener

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.

ParametersExpand Collapse

--column: optional array of FieldRef { name, lookback, period, value_type }

Subset of fields to include in the response.

Deprecated--field-filter: optional array of FieldRef { name, lookback, period, value_type }

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

--filter: optional array of SearchFilter { left, op, right }

Filter conditions to apply.

--page-size: optional number

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

--page-token: optional string

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

--sort-case-sensitive: optional boolean

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

--sort: optional array of SortSpec { field, direction }

Multi-field sort specifications.

ReturnsExpand Collapse

V1ScreenerSearchScreenerResponse: BaseResponse { metadata, error }

data: array of ScreenerRow { field, name, value, type }

field: object { name, lookback, period, value_type }

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

name: string

The field name.

lookback: optional "ONE_DAY" or "ONE_WEEK" or "ONE_MONTH" or 4 more

Optional historical lookback window.

"ONE_DAY"

"ONE_WEEK"

"ONE_MONTH"

"THREE_MONTHS"

"SIX_MONTHS"

"YEAR_TO_DATE"

"ONE_YEAR"

period: optional "QUARTER" or "TRAILING_TWELVE_MONTHS"

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

"QUARTER"

"TRAILING_TWELVE_MONTHS"

value_type: optional "DECIMAL" or "INTEGER" or "STRING" or 2 more

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

"DECIMAL"

"INTEGER"

"STRING"

"ANALYST_RATING"

"DATE"

name: string

Human-readable display name for this field

value: number or string

union_member_0: number

union_member_1: string

type: optional string

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

Search Screener

clst v1:screener search-screener \
  --api-key 'My API Key'

{
  "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"
  }
}

{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: unknown field `sort_by` at line 3 column 18"
  },
  "metadata": {
    "request_id": "69f02ce8-20e3-4bcd-a134-bb006eca5749"
  }
}

Returns Examples

{
  "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"
  }
}

{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: unknown field `sort_by` at line 3 column 18"
  },
  "metadata": {
    "request_id": "69f02ce8-20e3-4bcd-a134-bb006eca5749"
  }
}