Search Screener

client.V1.Screener.SearchScreener(ctx, body) (*V1ScreenerSearchScreenerResponse, error)

POST/v1/screener

Search instruments using structured filters.

Compose a request with filters, plus optional sorts, columns, and page_size/page_token for pagination. Each filter pairs a field reference (left) with an operator (op, e.g. GREATER_OR_EQUAL, BETWEEN) and comparison values (right), which can be literals or date variables such as today with a modifier. Field names, periods, and lookbacks come from the screener field catalog. sorts order results; columns selects which fields appear in each row (the default field set when omitted).

The response is a paginated, columnar list of matching instruments. Each row is an array of column objects, each with a display name, the field reference, an optional value type hint (e.g. CURR_USD, PERCENT), and the value. An instrument_id column is always prepended. Metadata carries total_items, total_pages, and next_page_token for paging.

Screener results can shuffle between calls; reconcile by re-checking rows across pages rather than assuming stable ordering.

ParametersExpand Collapse

body V1ScreenerSearchScreenerParams

Columns param.Field[[]FieldRef]Optional

Subset of fields to include in the response.

Name string

The field name.

Lookback FieldLookbackOptional

Optional historical lookback window.

One of the following:

const FieldLookbackOneDay FieldLookback = "ONE_DAY"

const FieldLookbackOneWeek FieldLookback = "ONE_WEEK"

const FieldLookbackOneMonth FieldLookback = "ONE_MONTH"

const FieldLookbackThreeMonths FieldLookback = "THREE_MONTHS"

const FieldLookbackSixMonths FieldLookback = "SIX_MONTHS"

const FieldLookbackYearToDate FieldLookback = "YEAR_TO_DATE"

const FieldLookbackOneYear FieldLookback = "ONE_YEAR"

Period FieldPeriodOptional

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

One of the following:

const FieldPeriodQuarter FieldPeriod = "QUARTER"

const FieldPeriodTrailingTwelveMonths FieldPeriod = "TRAILING_TWELVE_MONTHS"

const FieldPeriodAnnual FieldPeriod = "ANNUAL"

ValueType FieldTypeOptional

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

One of the following:

const FieldTypeDecimal FieldType = "DECIMAL"

const FieldTypeInteger FieldType = "INTEGER"

const FieldTypeString FieldType = "STRING"

const FieldTypeAnalystRating FieldType = "ANALYST_RATING"

const FieldTypeDate FieldType = "DATE"

Filters param.Field[[]SearchFilter]Optional

Filter conditions to apply.

The field to filter on.

The field name.

Optional historical lookback window.

One of the following:

const FieldLookbackOneDay FieldLookback = "ONE_DAY"

const FieldLookbackOneWeek FieldLookback = "ONE_WEEK"

const FieldLookbackOneMonth FieldLookback = "ONE_MONTH"

const FieldLookbackThreeMonths FieldLookback = "THREE_MONTHS"

const FieldLookbackSixMonths FieldLookback = "SIX_MONTHS"

const FieldLookbackYearToDate FieldLookback = "YEAR_TO_DATE"

const FieldLookbackOneYear FieldLookback = "ONE_YEAR"

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

One of the following:

const FieldPeriodQuarter FieldPeriod = "QUARTER"

const FieldPeriodTrailingTwelveMonths FieldPeriod = "TRAILING_TWELVE_MONTHS"

const FieldPeriodAnnual FieldPeriod = "ANNUAL"

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

One of the following:

const FieldTypeDecimal FieldType = "DECIMAL"

const FieldTypeInteger FieldType = "INTEGER"

const FieldTypeString FieldType = "STRING"

const FieldTypeAnalystRating FieldType = "ANALYST_RATING"

const FieldTypeDate FieldType = "DATE"

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

The operator to apply.

One of the following:

const FilterOperatorLessThan FilterOperator = "LESS_THAN"

const FilterOperatorLessOrEqual FilterOperator = "LESS_OR_EQUAL"

const FilterOperatorGreaterThan FilterOperator = "GREATER_THAN"

const FilterOperatorGreaterOrEqual FilterOperator = "GREATER_OR_EQUAL"

const FilterOperatorEqual FilterOperator = "EQUAL"

const FilterOperatorBetween FilterOperator = "BETWEEN"

const FilterOperatorNotBetween FilterOperator = "NOT_BETWEEN"

const FilterOperatorOneOf FilterOperator = "ONE_OF"

const FilterOperatorRegex FilterOperator = "REGEX"

const FilterOperatorBeginsWith FilterOperator = "BEGINS_WITH"

const FilterOperatorEndsWith FilterOperator = "ENDS_WITH"

const FilterOperatorContains FilterOperator = "CONTAINS"

const FilterOperatorIsNull FilterOperator = "IS_NULL"

const FilterOperatorIsNotNull FilterOperator = "IS_NOT_NULL"

Optional arguments that modify operator behavior.

One of the following:

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

Value FilterValueValueUnionOptional

One of the following:

float64

string

Variable VariableOptional

A variable reference.

Name string

The variable name.

Lookback FieldLookbackOptional

Optional historical lookback window.

One of the following:

const FieldLookbackOneDay FieldLookback = "ONE_DAY"

const FieldLookbackOneWeek FieldLookback = "ONE_WEEK"

const FieldLookbackOneMonth FieldLookback = "ONE_MONTH"

const FieldLookbackThreeMonths FieldLookback = "THREE_MONTHS"

const FieldLookbackSixMonths FieldLookback = "SIX_MONTHS"

const FieldLookbackYearToDate FieldLookback = "YEAR_TO_DATE"

const FieldLookbackOneYear FieldLookback = "ONE_YEAR"

Modifier ModifierOptional

Optional arithmetic modifier.

Args []ModifierArgUnion

One of the following:

float64

string

Name ModifierOp

The modifier operation.

One of the following:

const ModifierOpAdd ModifierOp = "ADD"

const ModifierOpSubtract ModifierOp = "SUBTRACT"

Period FieldPeriodOptional

Optional reporting period.

One of the following:

const FieldPeriodQuarter FieldPeriod = "QUARTER"

const FieldPeriodTrailingTwelveMonths FieldPeriod = "TRAILING_TWELVE_MONTHS"

const FieldPeriodAnnual FieldPeriod = "ANNUAL"

PageSize param.Field[int64]Optional

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

minimum1

PageToken param.Field[string]Optional

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

formatbyte

SortCaseSensitive param.Field[bool]Optional

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

Sorts param.Field[[]SortSpec]Optional

Multi-field sort specifications.

Field FieldRef

The field to sort by.

Name string

The field name.

Lookback FieldLookbackOptional

Optional historical lookback window.

One of the following:

const FieldLookbackOneDay FieldLookback = "ONE_DAY"

const FieldLookbackOneWeek FieldLookback = "ONE_WEEK"

const FieldLookbackOneMonth FieldLookback = "ONE_MONTH"

const FieldLookbackThreeMonths FieldLookback = "THREE_MONTHS"

const FieldLookbackSixMonths FieldLookback = "SIX_MONTHS"

const FieldLookbackYearToDate FieldLookback = "YEAR_TO_DATE"

const FieldLookbackOneYear FieldLookback = "ONE_YEAR"

Period FieldPeriodOptional

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

One of the following:

const FieldPeriodQuarter FieldPeriod = "QUARTER"

const FieldPeriodTrailingTwelveMonths FieldPeriod = "TRAILING_TWELVE_MONTHS"

const FieldPeriodAnnual FieldPeriod = "ANNUAL"

ValueType FieldTypeOptional

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

One of the following:

const FieldTypeDecimal FieldType = "DECIMAL"

const FieldTypeInteger FieldType = "INTEGER"

const FieldTypeString FieldType = "STRING"

const FieldTypeAnalystRating FieldType = "ANALYST_RATING"

const FieldTypeDate FieldType = "DATE"

Direction SortDirectionOptional

Sort direction (defaults to DESC).

One of the following:

const SortDirectionAsc SortDirection = "ASC"

const SortDirectionDesc SortDirection = "DESC"

ReturnsExpand Collapse

type V1ScreenerSearchScreenerResponse struct{…}

Data ScreenerRowList

Field FieldRef

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

Name string

The field name.

Lookback FieldLookbackOptional

Optional historical lookback window.

One of the following:

const FieldLookbackOneDay FieldLookback = "ONE_DAY"

const FieldLookbackOneWeek FieldLookback = "ONE_WEEK"

const FieldLookbackOneMonth FieldLookback = "ONE_MONTH"

const FieldLookbackThreeMonths FieldLookback = "THREE_MONTHS"

const FieldLookbackSixMonths FieldLookback = "SIX_MONTHS"

const FieldLookbackYearToDate FieldLookback = "YEAR_TO_DATE"

const FieldLookbackOneYear FieldLookback = "ONE_YEAR"

Period FieldPeriodOptional

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

One of the following:

const FieldPeriodQuarter FieldPeriod = "QUARTER"

const FieldPeriodTrailingTwelveMonths FieldPeriod = "TRAILING_TWELVE_MONTHS"

const FieldPeriodAnnual FieldPeriod = "ANNUAL"

ValueType FieldTypeOptional

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

One of the following:

const FieldTypeDecimal FieldType = "DECIMAL"

const FieldTypeInteger FieldType = "INTEGER"

const FieldTypeString FieldType = "STRING"

const FieldTypeAnalystRating FieldType = "ANALYST_RATING"

const FieldTypeDate FieldType = "DATE"

Name string

Human-readable display name for this field

Value ScreenerColumnValueUnion

One of the following:

float64

string

Type stringOptional

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

package main

import (
  "context"
  "fmt"

  "github.com/clear-street/clear-street-go"
  "github.com/clear-street/clear-street-go/option"
)

func main() {
  client := clearstreet.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.V1.Screener.SearchScreener(context.TODO(), clearstreet.V1ScreenerSearchScreenerParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

{
  "data": [
    [
      {
        "field": {
          "name": "instrument_id"
        },
        "name": "Instrument ID",
        "value": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
      },
      {
        "field": {
          "name": "symbol",
          "value_type": "STRING"
        },
        "name": "Symbol",
        "value": "AAPL"
      },
      {
        "field": {
          "name": "price",
          "value_type": "DECIMAL"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": "305.91"
      },
      {
        "field": {
          "name": "market_cap",
          "value_type": "DECIMAL"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": "3561234567890"
      },
      {
        "field": {
          "name": "beta",
          "value_type": "DECIMAL"
        },
        "name": "Beta",
        "value": "1.20"
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct",
          "value_type": "DECIMAL"
        },
        "name": "Change (Lookback) % (1w)",
        "type": "PERCENT",
        "value": "2.35"
      },
      {
        "field": {
          "name": "consensus_rating",
          "value_type": "ANALYST_RATING"
        },
        "name": "Consensus Rating",
        "value": "STRONG_BUY"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER",
          "value_type": "DECIMAL"
        },
        "name": "Earnings Per Share (q)",
        "type": "CURR_USD",
        "value": "1.55"
      }
    ],
    [
      {
        "field": {
          "name": "instrument_id"
        },
        "name": "Instrument ID",
        "value": "b2b3b4b5-c2c3-d2d3-e2e3-e4e5e6e7e8e9"
      },
      {
        "field": {
          "name": "symbol",
          "value_type": "STRING"
        },
        "name": "Symbol",
        "value": "F"
      },
      {
        "field": {
          "name": "price",
          "value_type": "DECIMAL"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": "12.50"
      },
      {
        "field": {
          "name": "market_cap",
          "value_type": "DECIMAL"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": "45000000000"
      },
      {
        "field": {
          "name": "beta",
          "value_type": "DECIMAL"
        },
        "name": "Beta",
        "value": "1.50"
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct",
          "value_type": "DECIMAL"
        },
        "name": "Change (Lookback) % (1w)",
        "type": "PERCENT",
        "value": "-0.85"
      },
      {
        "field": {
          "name": "consensus_rating",
          "value_type": "ANALYST_RATING"
        },
        "name": "Consensus Rating",
        "value": "HOLD"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER",
          "value_type": "DECIMAL"
        },
        "name": "Earnings Per Share (q)",
        "type": "CURR_USD",
        "value": "0.23"
      }
    ]
  ],
  "metadata": {
    "next_page_token": "AAAAAAAAAAoAAAAAAAAAAg",
    "page_number": 1,
    "request_id": "1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f",
    "total_items": 142,
    "total_pages": 6
  }
}

{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: invalid digit found in string at line 1 column 29"
  },
  "metadata": {
    "request_id": "69f02ce8-20e3-4bcd-a134-bb006eca5749"
  }
}

Returns Examples

{
  "data": [
    [
      {
        "field": {
          "name": "instrument_id"
        },
        "name": "Instrument ID",
        "value": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
      },
      {
        "field": {
          "name": "symbol",
          "value_type": "STRING"
        },
        "name": "Symbol",
        "value": "AAPL"
      },
      {
        "field": {
          "name": "price",
          "value_type": "DECIMAL"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": "305.91"
      },
      {
        "field": {
          "name": "market_cap",
          "value_type": "DECIMAL"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": "3561234567890"
      },
      {
        "field": {
          "name": "beta",
          "value_type": "DECIMAL"
        },
        "name": "Beta",
        "value": "1.20"
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct",
          "value_type": "DECIMAL"
        },
        "name": "Change (Lookback) % (1w)",
        "type": "PERCENT",
        "value": "2.35"
      },
      {
        "field": {
          "name": "consensus_rating",
          "value_type": "ANALYST_RATING"
        },
        "name": "Consensus Rating",
        "value": "STRONG_BUY"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER",
          "value_type": "DECIMAL"
        },
        "name": "Earnings Per Share (q)",
        "type": "CURR_USD",
        "value": "1.55"
      }
    ],
    [
      {
        "field": {
          "name": "instrument_id"
        },
        "name": "Instrument ID",
        "value": "b2b3b4b5-c2c3-d2d3-e2e3-e4e5e6e7e8e9"
      },
      {
        "field": {
          "name": "symbol",
          "value_type": "STRING"
        },
        "name": "Symbol",
        "value": "F"
      },
      {
        "field": {
          "name": "price",
          "value_type": "DECIMAL"
        },
        "name": "Price",
        "type": "CURR_USD",
        "value": "12.50"
      },
      {
        "field": {
          "name": "market_cap",
          "value_type": "DECIMAL"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": "45000000000"
      },
      {
        "field": {
          "name": "beta",
          "value_type": "DECIMAL"
        },
        "name": "Beta",
        "value": "1.50"
      },
      {
        "field": {
          "lookback": "ONE_WEEK",
          "name": "change_pct",
          "value_type": "DECIMAL"
        },
        "name": "Change (Lookback) % (1w)",
        "type": "PERCENT",
        "value": "-0.85"
      },
      {
        "field": {
          "name": "consensus_rating",
          "value_type": "ANALYST_RATING"
        },
        "name": "Consensus Rating",
        "value": "HOLD"
      },
      {
        "field": {
          "name": "earnings_per_share",
          "period": "QUARTER",
          "value_type": "DECIMAL"
        },
        "name": "Earnings Per Share (q)",
        "type": "CURR_USD",
        "value": "0.23"
      }
    ]
  ],
  "metadata": {
    "next_page_token": "AAAAAAAAAAoAAAAAAAAAAg",
    "page_number": 1,
    "request_id": "1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f",
    "total_items": 142,
    "total_pages": 6
  }
}

{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: invalid digit found in string at line 1 column 29"
  },
  "metadata": {
    "request_id": "69f02ce8-20e3-4bcd-a134-bb006eca5749"
  }
}