Screener API Manual

Screener Metadata Guide

Reference for all six screeners (Stock, Crypto, ETF, Bond, CEX, DEX): endpoints, request parameters, filter fields, preset field groups, and ready-to-run examples.

Browse screener reference Back to metadata browser
WorkflowEndpointsRequest ParametersFilter GrammarScreener ReferencePitfalls
Focused Scope

One manual for six screeners

Use this page when you need valid screener field IDs, enum sources, preset column groups, and request-shape guidance for the asset-specific scan endpoints. For broader discovery across exchanges and asset metadata, jump back to Metadata Browser or the main docs page.

6 asset types Live JSON-backed metadata Curl-first examples
Workflow

Three calls to a working screener

Every screener integration follows the same metadata-first flow, regardless of asset type.

01

Discover filter metadata

Fetch the filter field definitions and enum dictionaries for your asset type.

GET /api/screener/filter-options?asset_type=crypto&lang=en
  • asset_type: stock (default), crypto, etf, bond, cex, dex.
  • lang localizes enum labels.
  • id optionally narrows to specific enum sources.
02

Discover output presets

List the preset column groups available for the same asset type.

GET /api/screener/presets?asset_type=crypto
  • Use preset id values in preset_fields.
  • Presets control output columns only, never filtering.
  • Append individual columns with extra_fields.
03

Run the scan request

POST to the asset-specific scan endpoint with pagination, columns, filters, and sorting.

POST /api/screener/crypto/scan
  • range must be [start, endExclusive].
  • filters and sort use field IDs from step 1.
  • Only the stock screener accepts market.

Endpoint Overview

The screener API is 6 asset-specific scan endpoints plus 2 shared metadata endpoints. Metadata endpoints take asset_type as a query parameter; when omitted they default to stock.

Method Path Purpose
POST /api/screener/scan Scan stock assets with filters, presets, and sorting
POST /api/screener/crypto/scan Scan crypto assets with filters, presets, and sorting
POST /api/screener/etf/scan Scan etf assets with filters, presets, and sorting
POST /api/screener/bond/scan Scan bond assets with filters, presets, and sorting
POST /api/screener/cex/scan Scan cex assets with filters, presets, and sorting
POST /api/screener/dex/scan Scan dex assets with filters, presets, and sorting
GET /api/screener/presets?asset_type={type} List preset field-group IDs for the chosen asset type
GET /api/screener/filter-options?asset_type={type} Filter field definitions plus enum value dictionaries (supports lang and id)

Scan Request Parameters

Every scan endpoint accepts the same JSON body. Parameters may also be sent as query strings; JSON fields like filters and sort must then be JSON-encoded strings.

Parameter Type Applies to Description
market string stock only TradingView market segment, e.g. america, china, global. See the market list in the Stock tab.
lang string all Language code for localized .tr columns and enum labels, e.g. en, zh.
range [int, int] all Pagination window [start, endExclusive]. Example: [0, 50] returns the first 50 rows.
preset_fields string | string[] all Preset field-group IDs that control output columns. Valid IDs are listed per asset type below.
fields string | string[] all Explicit output column list. Accepts an array or a comma-separated string.
extra_fields string | string[] all Columns appended after presets/fields. Duplicates are removed automatically.
filters object all Map of fieldId → condition. See the filter grammar section for accepted shapes.
sort object all { "sortBy": fieldId, "sortOrder": "asc" | "desc" }. sortBy must be a real screener field.

Filter Grammar

Each key in filters is a field id from the filter field tables below. The value can take three shapes; the API normalizes them into TradingView scanner expressions.

Shape Example Interpretation
Enum array shorthand "sector": ["Health Services"] Treated as in_range over the given enum values. Best for enum fields.
Scalar shorthand "close": 10 Treated as equal.
Explicit operation object "market_cap_basic": { "operation": "greater_or_equal", "value": 1000000000 } Uses the operation as-is. Required for comparisons, ranges, and date filters.

Operations by value type

Each filter field declares a valueType. Only the operations listed for that type are accepted. For in_range / not_in_range, pass value as a two-element array (numbers/dates) or a value list (enums).

number

equalnot_equalgreatergreater_or_equallessless_or_equalin_rangenot_in_rangeemptynempty

enum

equalnot_equalin_rangenot_in_rangeemptynempty

date

equalgreatergreater_or_equallessless_or_equalin_rangenot_in_rangeemptynempty
Screener Reference

Per-screener parameter reference

Pick an asset type to see its scan endpoint, searchable filter fields, preset groups, enum sources, and a ready-to-run example.

Common Mistakes to Avoid

  • Do not use translated labels as filter keys. Use the field id from metadata, such as sector.
  • Do not rename filter keys. AnalystRating stays AnalystRating; the filter key and enum source are not always the same string.
  • Do not reuse stock filter fields for other asset types. Each screener has its own field set — check the tab above.
  • Do not send market to non-stock screeners; it is ignored everywhere except /api/screener/scan.
  • Do not send malformed pagination such as [20] or non-integer strings in range.
  • Do not guess enum values. Resolve them from /api/screener/filter-options with the matching asset_type.