Get Screener Catalog

GET/v1/screener/catalog

Returns the complete screener field catalog: the field kinds, the per-field data, the enum universes, the request-side rules, the built-in variables and modifiers, and the POST /screener default response fields.

POST /screener field references are validated against this catalog; its rules object documents how to compose a valid request.

ReturnsExpand Collapse

data: Catalog { default_response_fields, enums, fields, 6 more }

The complete screener field catalog, serialized as the data payload of GET /screener/catalog.

default_response_fields: array of string

The api_names that resolve to the POST default column set when columns is omitted.

enums: Enums { builtin_variable, category, date_unit, 7 more }

The enum universes every other section’s values are drawn from.

builtin_variable: array of string

The built-in variable names, e.g. "today", "start_of_year".

category: array of string

FieldCategory variants, e.g. "PROFILE", "VALUATION".

date_unit: array of string

The modifier date units, e.g. "DAY", "YEAR".

format: array of string

FieldFormat variants, e.g. "CURRENCY", "PERCENT".

lookback: array of string

FieldLookback variants, e.g. "ONE_WEEK", "YEAR_TO_DATE".

modifier_op: array of string

The modifier operation names, "ADD" and "SUBTRACT".

operator: array of string

FilterOperator variants, e.g. "BETWEEN", "ONE_OF".

operator_arg: array of string

The modifier arg forms, e.g. "LEFT_INCLUSIVE".

period: array of string

FieldPeriod variants, e.g. "QUARTER", "ANNUAL".

value_type: array of string

FieldValueType variants, e.g. "DECIMAL", "DATE".

fields: FieldColumns { description, display_name, kind, name }

Struct-of-arrays of the remaining per-field scalars.

description: array of string

A human-readable description of the field.

display_name: array of string

The display name of the column when no period / lookback is set.

kind: array of number

Index into Catalog::kinds.

The base field name, as accepted in a request’s left.name / right[].variable field reference.

kinds: array of FieldKind { category, combinations, default_combination, 2 more }

The deduplicated (category, format, value_type, combinations, default combination) tuples; fields.kind[i] indexes into this.

category: string

The field’s category, a member of enums.category.

combinations: array of Combination { lookback, period }

Ordered, in declaration order. The empty combination is the current or most recent value.

lookback: optional string

The lookback, a member of enums.lookback.

period: optional string

The period, a member of enums.period.

default_combination: Combination { lookback, period }

The combination a bare field reference resolves to: the field’s current or most recent value when the kind offers it, otherwise the kind’s default period / lookback.

lookback: optional string

The lookback, a member of enums.lookback.

period: optional string

The period, a member of enums.period.

format: string

The field’s format, a member of enums.format.

value_type: string

The field’s value type, a member of enums.value_type.

modifiers: array of ModifierDef { args, name }

The modifier operations and their legal args forms.

args: array of ModifierArg { kind, note, position, 3 more }

The positional args slots, in order.

kind: string

"NUMBER" or "ENUM".

note: string

The arg’s meaning and constraints.

position: number

Zero-based position in the args array.

formatint32

minimum0

required: boolean

Whether the arg must be present in every modifier use.

default: optional string

For optional args: the value used when the arg is omitted.

ref: optional string

For "ENUM" args: the enums list the value must be a member of.

The modifier operation name: one of "ADD" or "SUBTRACT".

operators_by_value_type: map[array of string]

value_type -> canonically-ordered valid operators.

rules: Rules { api_name_composition, axes, defaults, 3 more }

Request-side semantics for turning the data into a valid call.

api_name_composition: string

Requests and response field objects use the same reference shape: base name plus at most one of period / lookback; default_response_fields (the POST default column set when columns is omitted) carries api_names, each decoding via suffixes.

axes: string

At most one of period / lookback; the empty combination selects the field’s current or most recent value.

defaults: string

Omitting both is always valid; it resolves to the field’s current or most recent value when the kind offers it, otherwise to default_combination.

modifiers: string

Where modifier is legal, its args forms, and unit semantics.

operators: string

Filter operator value counts for the right array.

variables: string

Built-in variables and field references in right[].variable.

suffixes: map[string]

Axis token -> abbreviation, for every token in use in kinds.

variables: array of VariableDef { description, name, resolves_to }

The built-in variables accepted in filters[].right[].variable.

description: string

A human-readable description of what the variable resolves to.

The variable name as accepted in filters[].right[].variable.

resolves_to: string

What the variable resolves to at call time (DATE for all built-ins).

Get Screener Catalog

curl https://api.clearstreet.com/v1/screener/catalog \
    -H "Authorization: Bearer $API_KEY"

{
  "data": {
    "default_response_fields": [
      "market_cap",
      "earnings_per_share_ttm"
    ],
    "enums": {
      "builtin_variable": [
        "today",
        "start_of_week",
        "start_of_month",
        "start_of_quarter",
        "start_of_year"
      ],
      "category": [
        "PROFILE",
        "MARKET_DATA"
      ],
      "date_unit": [
        "DAY",
        "WEEK",
        "MONTH",
        "YEAR"
      ],
      "format": [
        "CURRENCY",
        "PERCENT",
        "RATIO",
        "COUNT",
        "NONE"
      ],
      "lookback": [
        "ONE_DAY",
        "ONE_WEEK",
        "ONE_MONTH",
        "THREE_MONTHS",
        "SIX_MONTHS",
        "YEAR_TO_DATE",
        "ONE_YEAR"
      ],
      "modifier_op": [
        "ADD",
        "SUBTRACT"
      ],
      "operator": [
        "LESS_THAN",
        "LESS_OR_EQUAL",
        "GREATER_THAN",
        "GREATER_OR_EQUAL",
        "EQUAL",
        "BETWEEN"
      ],
      "operator_arg": [
        "LEFT_INCLUSIVE",
        "RIGHT_INCLUSIVE",
        "LEFT_EXCLUSIVE",
        "RIGHT_EXCLUSIVE",
        "CASE_INSENSITIVE"
      ],
      "period": [
        "QUARTER",
        "TRAILING_TWELVE_MONTHS",
        "ANNUAL"
      ],
      "value_type": [
        "DECIMAL",
        "INTEGER",
        "STRING",
        "ANALYST_RATING",
        "DATE"
      ]
    },
    "fields": {
      "description": [
        "Trading symbol",
        "Market Identifier Code (MIC) for primary exchange"
      ],
      "display_name": [
        "Symbol",
        "Security Exchange"
      ],
      "kind": [
        0,
        0
      ],
      "name": [
        "symbol",
        "security_exchange"
      ]
    },
    "kinds": [
      {
        "category": "PROFILE",
        "combinations": [
          {}
        ],
        "default_combination": {},
        "format": "NONE",
        "value_type": "STRING"
      },
      {
        "category": "PROFILE",
        "combinations": [
          {}
        ],
        "default_combination": {},
        "format": "COUNT",
        "value_type": "INTEGER"
      }
    ],
    "modifiers": [
      {
        "args": [
          {
            "kind": "NUMBER",
            "note": "Positive integer for date built-ins; any number for numeric BETWEEN field-ref bounds.",
            "position": 0,
            "required": true
          },
          {
            "default": "DAY",
            "kind": "ENUM",
            "note": "Date built-ins only; ignored on numeric BETWEEN bounds.",
            "position": 1,
            "ref": "date_unit",
            "required": false
          }
        ],
        "name": "ADD"
      }
    ],
    "operators_by_value_type": {
      "ANALYST_RATING": [
        "EQUAL",
        "ONE_OF",
        "IS_NULL",
        "IS_NOT_NULL"
      ]
    },
    "rules": {
      "api_name_composition": "A POST /screener request and the response `field` objects use the same reference shape: base `name` plus at most one of `period` / `lookback`. The suffixed api_name (`{base}_{suffix}`) is never accepted in a request and never returned in a response. Each response column is `{\"name\": <display name>, \"field\": <field reference>, \"type\": <format hint when applicable>, \"value\": <value>}`; the display name of a parameterized column is `{display_name} ({suffix})` (e.g. `Earnings Per Share (ttm)`), and a column showing the field's current or most recent value is the bare `display_name`. The suffixed api_name appears only in `default_response_fields`, where each entry decodes via `suffixes` to a column's `(base name, period or lookback)`.",
      "axes": "A combination carries at most one of `period` / `lookback`; the API rejects both together. The empty combination selects the field's current or most recent value and is present only when the kind offers it.",
      "defaults": "Omitting both `period` and `lookback` from a field reference is always valid. It resolves to the field's current or most recent value when the kind offers it, otherwise to the kind's `default_combination`; the bare base `name` is therefore a valid field reference for every field.",
      "modifiers": "A `modifier` is `{\"name\": \"ADD\" | \"SUBTRACT\", \"args\": [...]}` and shifts a variable's value. On a date built-in it is valid under comparisons, `BETWEEN` / `NOT_BETWEEN` bounds, and `ONE_OF`: `args` is `[amount]` or `[amount, unit]`, `amount` is a positive integer, `unit` is one of `DAY`, `WEEK`, `MONTH`, `YEAR` and defaults to `DAY`, and `ADD` shifts forward while `SUBTRACT` shifts backward. On a numeric `BETWEEN` bound that is a field reference, `args` is `[amount]` where `amount` is any number, `ADD` adds and `SUBTRACT` subtracts, and any `unit` arg is ignored. A modifier is rejected on a field reference outside a numeric `BETWEEN` bound and in `NOT_BETWEEN`.",
      "operators": "`BETWEEN` and `NOT_BETWEEN` take exactly two `right` values; `ONE_OF` takes one or more; all other operators take exactly one; `IS_NULL` and `IS_NOT_NULL` take none (omit `right`).",
      "variables": "A `right` entry is either a literal `value` or a `variable` reference, never both. The built-in variables are `today`, `start_of_week`, `start_of_month`, `start_of_quarter`, and `start_of_year`; each resolves to a date in the server's local timezone, cannot carry `period` or `lookback`, and is valid on `DATE` fields (comparisons, `BETWEEN` / `NOT_BETWEEN` bounds, and `ONE_OF`). Any other variable name is a field reference and must resolve as a field in `fields`, carrying at most one of `period` / `lookback`; field references are valid as comparison values and as `BETWEEN` bounds when the two fields' `value_type`s are comparable, and are rejected in `NOT_BETWEEN`."
    },
    "suffixes": {
      "ANNUAL": "a",
      "QUARTER": "q",
      "TRAILING_TWELVE_MONTHS": "ttm"
    },
    "variables": [
      {
        "description": "The current date in the server's local timezone.",
        "name": "today",
        "resolves_to": "DATE"
      }
    ]
  },
  "error": null,
  "metadata": {
    "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}

Returns Examples

{
  "data": {
    "default_response_fields": [
      "market_cap",
      "earnings_per_share_ttm"
    ],
    "enums": {
      "builtin_variable": [
        "today",
        "start_of_week",
        "start_of_month",
        "start_of_quarter",
        "start_of_year"
      ],
      "category": [
        "PROFILE",
        "MARKET_DATA"
      ],
      "date_unit": [
        "DAY",
        "WEEK",
        "MONTH",
        "YEAR"
      ],
      "format": [
        "CURRENCY",
        "PERCENT",
        "RATIO",
        "COUNT",
        "NONE"
      ],
      "lookback": [
        "ONE_DAY",
        "ONE_WEEK",
        "ONE_MONTH",
        "THREE_MONTHS",
        "SIX_MONTHS",
        "YEAR_TO_DATE",
        "ONE_YEAR"
      ],
      "modifier_op": [
        "ADD",
        "SUBTRACT"
      ],
      "operator": [
        "LESS_THAN",
        "LESS_OR_EQUAL",
        "GREATER_THAN",
        "GREATER_OR_EQUAL",
        "EQUAL",
        "BETWEEN"
      ],
      "operator_arg": [
        "LEFT_INCLUSIVE",
        "RIGHT_INCLUSIVE",
        "LEFT_EXCLUSIVE",
        "RIGHT_EXCLUSIVE",
        "CASE_INSENSITIVE"
      ],
      "period": [
        "QUARTER",
        "TRAILING_TWELVE_MONTHS",
        "ANNUAL"
      ],
      "value_type": [
        "DECIMAL",
        "INTEGER",
        "STRING",
        "ANALYST_RATING",
        "DATE"
      ]
    },
    "fields": {
      "description": [
        "Trading symbol",
        "Market Identifier Code (MIC) for primary exchange"
      ],
      "display_name": [
        "Symbol",
        "Security Exchange"
      ],
      "kind": [
        0,
        0
      ],
      "name": [
        "symbol",
        "security_exchange"
      ]
    },
    "kinds": [
      {
        "category": "PROFILE",
        "combinations": [
          {}
        ],
        "default_combination": {},
        "format": "NONE",
        "value_type": "STRING"
      },
      {
        "category": "PROFILE",
        "combinations": [
          {}
        ],
        "default_combination": {},
        "format": "COUNT",
        "value_type": "INTEGER"
      }
    ],
    "modifiers": [
      {
        "args": [
          {
            "kind": "NUMBER",
            "note": "Positive integer for date built-ins; any number for numeric BETWEEN field-ref bounds.",
            "position": 0,
            "required": true
          },
          {
            "default": "DAY",
            "kind": "ENUM",
            "note": "Date built-ins only; ignored on numeric BETWEEN bounds.",
            "position": 1,
            "ref": "date_unit",
            "required": false
          }
        ],
        "name": "ADD"
      }
    ],
    "operators_by_value_type": {
      "ANALYST_RATING": [
        "EQUAL",
        "ONE_OF",
        "IS_NULL",
        "IS_NOT_NULL"
      ]
    },
    "rules": {
      "api_name_composition": "A POST /screener request and the response `field` objects use the same reference shape: base `name` plus at most one of `period` / `lookback`. The suffixed api_name (`{base}_{suffix}`) is never accepted in a request and never returned in a response. Each response column is `{\"name\": <display name>, \"field\": <field reference>, \"type\": <format hint when applicable>, \"value\": <value>}`; the display name of a parameterized column is `{display_name} ({suffix})` (e.g. `Earnings Per Share (ttm)`), and a column showing the field's current or most recent value is the bare `display_name`. The suffixed api_name appears only in `default_response_fields`, where each entry decodes via `suffixes` to a column's `(base name, period or lookback)`.",
      "axes": "A combination carries at most one of `period` / `lookback`; the API rejects both together. The empty combination selects the field's current or most recent value and is present only when the kind offers it.",
      "defaults": "Omitting both `period` and `lookback` from a field reference is always valid. It resolves to the field's current or most recent value when the kind offers it, otherwise to the kind's `default_combination`; the bare base `name` is therefore a valid field reference for every field.",
      "modifiers": "A `modifier` is `{\"name\": \"ADD\" | \"SUBTRACT\", \"args\": [...]}` and shifts a variable's value. On a date built-in it is valid under comparisons, `BETWEEN` / `NOT_BETWEEN` bounds, and `ONE_OF`: `args` is `[amount]` or `[amount, unit]`, `amount` is a positive integer, `unit` is one of `DAY`, `WEEK`, `MONTH`, `YEAR` and defaults to `DAY`, and `ADD` shifts forward while `SUBTRACT` shifts backward. On a numeric `BETWEEN` bound that is a field reference, `args` is `[amount]` where `amount` is any number, `ADD` adds and `SUBTRACT` subtracts, and any `unit` arg is ignored. A modifier is rejected on a field reference outside a numeric `BETWEEN` bound and in `NOT_BETWEEN`.",
      "operators": "`BETWEEN` and `NOT_BETWEEN` take exactly two `right` values; `ONE_OF` takes one or more; all other operators take exactly one; `IS_NULL` and `IS_NOT_NULL` take none (omit `right`).",
      "variables": "A `right` entry is either a literal `value` or a `variable` reference, never both. The built-in variables are `today`, `start_of_week`, `start_of_month`, `start_of_quarter`, and `start_of_year`; each resolves to a date in the server's local timezone, cannot carry `period` or `lookback`, and is valid on `DATE` fields (comparisons, `BETWEEN` / `NOT_BETWEEN` bounds, and `ONE_OF`). Any other variable name is a field reference and must resolve as a field in `fields`, carrying at most one of `period` / `lookback`; field references are valid as comparison values and as `BETWEEN` bounds when the two fields' `value_type`s are comparable, and are rejected in `NOT_BETWEEN`."
    },
    "suffixes": {
      "ANNUAL": "a",
      "QUARTER": "q",
      "TRAILING_TWELVE_MONTHS": "ttm"
    },
    "variables": [
      {
        "description": "The current date in the server's local timezone.",
        "name": "today",
        "resolves_to": "DATE"
      }
    ]
  },
  "error": null,
  "metadata": {
    "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}