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

Create Screener

POST/v1/saved-screeners

Create a saved screener configuration.

Persists a screener configuration for the authenticated user.

Body ParametersJSONExpand Collapse
columns: optional array of FieldRef { name, lookback, period, value_type }

Structured field references to include when running this screener

name: string

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"
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"
Deprecatedfield_filter: optional array of FieldRef { name, lookback, period, value_type }

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

name: string

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"
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 array of SearchFilter { left, op, right }

Structured search filter criteria

left: FieldRef { name, lookback, period, value_type }

The field to filter on.

name: string

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"
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 { name, args }

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 array of OperatorArg

Optional arguments that modify operator behavior.

One of the following:
"LEFT_INCLUSIVE"
"RIGHT_INCLUSIVE"
"LEFT_EXCLUSIVE"
"RIGHT_EXCLUSIVE"
"CASE_INSENSITIVE"
right: optional array of FilterValue { value, variable }

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

value: optional number or string
One of the following:
number
string
variable: optional Variable { name, lookback, modifier, period }

A variable reference.

name: string

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 { args, name }

Optional arithmetic modifier.

args: array of number or string
One of the following:
number
string

The modifier operation.

One of the following:
"ADD"
"SUBTRACT"
period: optional FieldPeriod

Optional reporting period.

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
name: optional string

The name for this screener configuration

sorts: optional array of SortSpec { field, direction }

Multi-field sort specifications

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

The field to sort by.

name: string

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"
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
data: ScreenerEntry { id, created_at, filters, 5 more }

A saved screener configuration entry

id: string
created_at: string
filters: array of SearchFilter { left, op, right }
left: FieldRef { name, lookback, period, value_type }

The field to filter on.

name: string

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"
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 { name, args }

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 array of OperatorArg

Optional arguments that modify operator behavior.

One of the following:
"LEFT_INCLUSIVE"
"RIGHT_INCLUSIVE"
"LEFT_EXCLUSIVE"
"RIGHT_EXCLUSIVE"
"CASE_INSENSITIVE"
right: optional array of FilterValue { value, variable }

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

value: optional number or string
One of the following:
number
string
variable: optional Variable { name, lookback, modifier, period }

A variable reference.

name: string

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 { args, name }

Optional arithmetic modifier.

args: array of number or string
One of the following:
number
string

The modifier operation.

One of the following:
"ADD"
"SUBTRACT"
period: optional FieldPeriod

Optional reporting period.

One of the following:
"QUARTER"
"TRAILING_TWELVE_MONTHS"
name: string
updated_at: string
columns: optional array of FieldRef { name, lookback, period, value_type }

Field references included when running this screener.

name: string

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"
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"
Deprecatedfield_filter: optional array of FieldRef { name, lookback, period, value_type }

Deprecated: use columns instead. Mirrors columns.

name: string

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"
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 array of SortSpec { field, direction }
field: FieldRef { name, lookback, period, value_type }

The field to sort by.

name: string

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

Create Screener

curl https://api.clearstreet.com/v1/saved-screeners \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $API_KEY" \
    -d '{}'
{
  "data": {
    "columns": [
      {
        "name": "symbol"
      },
      {
        "name": "price"
      },
      {
        "name": "market_cap"
      }
    ],
    "created_at": "2026-03-20T14:30:00Z",
    "filters": [
      {
        "left": {
          "name": "market_cap"
        },
        "op": {
          "name": "GREATER_OR_EQUAL"
        },
        "right": [
          {
            "value": 1000000000
          }
        ]
      }
    ],
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Tech Large Caps",
    "sorts": [
      {
        "direction": "DESC",
        "field": {
          "name": "market_cap"
        }
      }
    ],
    "updated_at": "2026-03-20T14:30:00Z"
  },
  "metadata": {
    "request_id": "1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f"
  }
}
{
  "error": {
    "code": 400,
    "message": "Failed to parse the request body as JSON: trailing comma at line 3 column 1"
  },
  "metadata": {
    "request_id": "a91ced80-b496-44af-a923-b8b8f1fbdc83"
  }
}
Returns Examples
{
  "data": {
    "columns": [
      {
        "name": "symbol"
      },
      {
        "name": "price"
      },
      {
        "name": "market_cap"
      }
    ],
    "created_at": "2026-03-20T14:30:00Z",
    "filters": [
      {
        "left": {
          "name": "market_cap"
        },
        "op": {
          "name": "GREATER_OR_EQUAL"
        },
        "right": [
          {
            "value": 1000000000
          }
        ]
      }
    ],
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Tech Large Caps",
    "sorts": [
      {
        "direction": "DESC",
        "field": {
          "name": "market_cap"
        }
      }
    ],
    "updated_at": "2026-03-20T14:30:00Z"
  },
  "metadata": {
    "request_id": "1a2b3c4d-5e6f-7890-1234-5a6b7c8d9e0f"
  }
}
{
  "error": {
    "code": 400,
    "message": "Failed to parse the request body as JSON: trailing comma at line 3 column 1"
  },
  "metadata": {
    "request_id": "a91ced80-b496-44af-a923-b8b8f1fbdc83"
  }
}