Screen Stocks

GET/v1/screener

Run the same powerful stock screen that powers the Vantafin web screener, programmatically. Filter the US equity universe across 80+ metrics spanning security info, live market data, technicals, TTM financials, valuation multiples, margins & returns, growth rates and dividends. Each filter is a 'metric:operator:value' clause and clauses combine with AND - pass the filter parameter multiple times to stack conditions (e.g. filter=peRatio:below:20&filter=marketCap:above:1e9&filter=revenueGrowthYoy:above:25). Numeric metrics support above, below, above_or_equal, below_or_equal, equal, between and outside; categorical metrics (sector, industry, country, exchange) match an exact comma-separated list; text metrics (ticker, company) support equal and contains. Sort by any metric, page with limit/offset, and request extra metric columns. Percent metrics are returned in percent units (25 = 25%) and dollar metrics in dollars (1e9 = $1B). Call Screener Fields for the full metric catalogue.

Use cases

Building custom stock screens (value, growth, momentum, dividend) on your own schedule
Quantitative research and factor backtests over the live universe
Powering alerts when stocks cross fundamental or technical thresholds
Generating watchlists and ranked tables for dashboards

Input parameters

Required

Parameter	Type	Description
filter	string	Repeatable. A 'metric:operator:value' clause (e.g. peRatio:below:20). Numeric operators: above, below, above_or_equal, below_or_equal, equal, between (two values, e.g. price:between:10:50), outside. Categorical metrics (sector, industry, country, exchange) use 'equal' with a comma-separated list (e.g. sector:equal:Technology,Healthcare; country uses ISO-2 codes). Text metrics (ticker, company) accept 'equal' or 'contains'.
sort	string	Metric id to sort by (default marketCap).
order	string	Sort direction: asc or desc (default desc).
columns	string	Comma-separated extra metric ids to include in each row.
limit	integer	Page size, 1-100 (default 50).
offset	integer	Row offset for pagination (default 0).

Output parameters

Field	Type	Description
results	array	Matching rows for this page, in sort order.
results[].ticker	string	Ticker symbol.
results[].company	string	Company name.
results[].sector	string	GICS sector.
results[].marketCap	float	Market capitalization (USD). Plus any other requested metric columns keyed by metric id.
count	integer	Number of rows in this response.
total	integer	Total number of stocks matching the filters.
limit	integer	Page size applied.
offset	integer	Row offset applied.
sort	string	Metric id the results were sorted by.
order	string	Sort direction: asc or desc.
columns	array	Metric ids present in each result row.
filters	array	The parsed filters that were applied (metric, op, values).

from vantafin import RESTClient

client = RESTClient("vf-live-your_api_key")

result = client.screener(filter=["sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9"], sort="marketCap", columns="peRatio,roe", limit=25)

print(result)

{
  "results": [
    {
      "ticker": "AAPL",
      "company": "Apple Inc.",
      "sector": "Technology",
      "industry": "Consumer Electronics",
      "country": "US",
      "exchange": "NASDAQ",
      "price": 248.5,
      "changeAbs": 1.32,
      "changePct": 0.53,
      "volume": 41200000,
      "usdVolume": 10238200000,
      "marketCap": 3760000000000,
      "peRatio": 19.4,
      "roe": 154.2
    },
    {
      "ticker": "MSFT",
      "company": "Microsoft Corporation",
      "sector": "Technology",
      "industry": "Software - Infrastructure",
      "country": "US",
      "exchange": "NASDAQ",
      "price": 432.1,
      "changeAbs": -2.1,
      "changePct": -0.48,
      "volume": 18900000,
      "usdVolume": 8166690000,
      "marketCap": 3210000000000,
      "peRatio": 18.1,
      "roe": 34.6
    }
  ],
  "count": 2,
  "total": 18,
  "limit": 25,
  "offset": 0,
  "sort": "marketCap",
  "order": "desc",
  "columns": [
    "ticker",
    "company",
    "sector",
    "industry",
    "country",
    "exchange",
    "price",
    "changeAbs",
    "changePct",
    "volume",
    "usdVolume",
    "marketCap",
    "peRatio",
    "roe"
  ],
  "filters": [
    {
      "metric": "sector",
      "op": "equal",
      "values": [
        "Technology"
      ]
    },
    {
      "metric": "peRatio",
      "op": "below",
      "values": [
        20
      ]
    },
    {
      "metric": "marketCap",
      "op": "above",
      "values": [
        1000000000
      ]
    }
  ]
}

Parameter

Type

Description

filter

string

Repeatable. A 'metric:operator:value' clause (e.g. peRatio:below:20). Numeric operators: above, below, above_or_equal, below_or_equal, equal, between (two values, e.g. price:between:10:50), outside. Categorical metrics (sector, industry, country, exchange) use 'equal' with a comma-separated list (e.g. sector:equal:Technology,Healthcare; country uses ISO-2 codes). Text metrics (ticker, company) accept 'equal' or 'contains'.

sort

string

Metric id to sort by (default marketCap).

order

string

Sort direction: asc or desc (default desc).

columns

string

Comma-separated extra metric ids to include in each row.

limit

integer

Page size, 1-100 (default 50).

offset

integer

Row offset for pagination (default 0).

Field

Type

Description

results

array

Matching rows for this page, in sort order.

results[].ticker

string

Ticker symbol.

results[].company

string

Company name.

results[].sector

string

GICS sector.

results[].marketCap

float

Market capitalization (USD). Plus any other requested metric columns keyed by metric id.

count

integer

Number of rows in this response.

total

integer

Total number of stocks matching the filters.

limit

integer

Page size applied.

offset

integer

Row offset applied.

sort

string

Metric id the results were sorted by.

order

string

Sort direction: asc or desc.

columns

array

Metric ids present in each result row.

filters

array

The parsed filters that were applied (metric, op, values).

from vantafin import RESTClient client = RESTClient("vf-live-your_api_key") result = client.screener(filter=["sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9"], sort="marketCap", columns="peRatio,roe", limit=25) print(result)

{ "results": [ { "ticker": "AAPL", "company": "Apple Inc.", "sector": "Technology", "industry": "Consumer Electronics", "country": "US", "exchange": "NASDAQ", "price": 248.5, "changeAbs": 1.32, "changePct": 0.53, "volume": 41200000, "usdVolume": 10238200000, "marketCap": 3760000000000, "peRatio": 19.4, "roe": 154.2 }, { "ticker": "MSFT", "company": "Microsoft Corporation", "sector": "Technology", "industry": "Software - Infrastructure", "country": "US", "exchange": "NASDAQ", "price": 432.1, "changeAbs": -2.1, "changePct": -0.48, "volume": 18900000, "usdVolume": 8166690000, "marketCap": 3210000000000, "peRatio": 18.1, "roe": 34.6 } ], "count": 2, "total": 18, "limit": 25, "offset": 0, "sort": "marketCap", "order": "desc", "columns": [ "ticker", "company", "sector", "industry", "country", "exchange", "price", "changeAbs", "changePct", "volume", "usdVolume", "marketCap", "peRatio", "roe" ], "filters": [ { "metric": "sector", "op": "equal", "values": [ "Technology" ] }, { "metric": "peRatio", "op": "below", "values": [ 20 ] }, { "metric": "marketCap", "op": "above", "values": [ 1000000000 ] } ] }

Docs

Screen Stocks

Input parameters

Output parameters

Docs

Screen Stocks

Input parameters

Output parameters