Financial Data API — Documentation

The equity screener is the company-level counterpart of the macro screener. Instead of filtering countries by indicator values, you filter the scored universe of US companies by the latest values of 34 screenable fields — valuation multiples, financial ratios, and price analytics — with the same compact filter DSL: “show me Technology companies with a trailing P/E below 25 and a positive 12-month return, ranked by free-cash-flow yield.”

The screener screens public values only: the latest published value per company per field, all of it derived from SEC fundamentals and Financial Data API’s own derived analytics. It never exposes internal scoring and never touches licensed data.

How it works

Filters arrive as a single filter query parameter. Each clause is field:operator:value, clauses are comma-separated, and they are AND-ed together — identical semantics to the macro screener:

filter=sector:eq:Technology,trailing_pe_ratio:lt:25,equity_return_12m:gt:0

The operators are gt, lt, gte, lte, eq, and in; in is the only one that takes more than one value, pipe-separated:

filter=sector:in:Technology|Health Care

A company qualifies only when every clause matches. A company missing a value for any filtered field does not satisfy that clause and is excluded — absence never counts as a match.

Parameters

Param	Values	Description
`filter`	DSL string, required	Comma-joined `field:operator:value` clauses, AND-ed.
`sort`	Any screenable field, plus `ticker` and `name`; default `ticker`	Field to rank the results by. Companies missing the sort field sort last.
`order`	`asc` / `desc`, default `asc`	Sort direction.
`limit`	1 to 200, default 50	Cap the number of returned companies.

Unknown query parameters, malformed clauses, unknown operators, and out-of-range limit values are rejected with bad_request. The error message names the offending clause.

Screenable fields

The 34 fields fall into five groups. sector and industry are strings and accept eq and in only, matched case-insensitively; every other field is numeric and accepts all six operators.

Classification and size

sector, industry (string; eq/in, case-insensitive), market_cap.

Valuation multiples (13)

trailing_pe_ratio, price_to_book_ratio, price_to_sales_ratio, price_to_free_cash_flow_ratio, price_to_operating_cash_flow_ratio, ev_to_ebit_ratio, ev_to_ebitda_ratio, ev_to_sales_ratio, ev_to_free_cash_flow_ratio, earnings_yield, free_cash_flow_yield, dividend_yield, peg_ratio.

Financial ratios (10)

gross_margin, operating_margin, profit_margin, free_cash_flow_margin, current_ratio, quick_ratio, cash_ratio, debt_to_equity, return_on_assets, return_on_equity.

Price analytics (8)

equity_return_1m, equity_return_3m, equity_return_6m, equity_return_12m, equity_realized_vol_30d, equity_realized_vol_90d, equity_max_drawdown_1y, equity_trend_zscore_90d.

Discovering fields

The authoritative list, with operators, syntax, and an example, lives at GET /public/equity-screener/filters:

curl "https://api.financialdatapi.com/public/equity-screener/filters" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

const { data } = await client.request("/public/equity-screener/filters");
for (const f of data.fields) {
  console.log(f.field, "-", f.name);
}

Treat /public/equity-screener/filters as the source of truth for field names rather than hard-coding the list above — the same pattern as the macro screener’s /screener/filters.

Running a screen

Send your clauses as the filter parameter to GET /public/equity-screener. The filter parameter is required.

curl "https://api.financialdatapi.com/public/equity-screener?filter=sector:eq:Technology,trailing_pe_ratio:lt:25,equity_return_12m:gt:0&sort=free_cash_flow_yield&order=desc" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

const { data } = await client.request("/public/equity-screener", {
  filter: "sector:eq:Technology,trailing_pe_ratio:lt:25,equity_return_12m:gt:0",
  sort: "free_cash_flow_yield",
  order: "desc",
});

for (const row of data) {
  console.log(row.ticker, row.name, row.values);
}

The response

Each result is a company that satisfied every clause, with the evaluated values inlined so you can see what it screened on without a second call:

Response

{
  "data": [
    {
      "entityId": "ent_aapl",
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "sector": "Technology",
      "industry": "Technology Hardware, Storage & Peripherals",
      "values": [
        { "field": "trailing_pe_ratio", "value": 23.4, "unit": "ratio", "periodEnd": "2026-07-24" },
        { "field": "equity_return_12m", "value": 8.6, "unit": "percent", "periodEnd": "2026-07-24" },
        { "field": "free_cash_flow_yield", "value": 4.1, "unit": "percent", "periodEnd": "2026-07-24" }
      ]
    }
  ],
  "meta": { "api_version": "v1" },
  "requestId": "..."
}

Example values above are illustrative. Run the screen for live results.

Authentication

The equity screener lives on the public surface. Send your key as x-api-key (or Authorization: Bearer) as everywhere else; see Authentication.

Notes and caveats

The universe

The screener evaluates the scored universe — S&P 500 union Nasdaq-100, the same membership as GET /companies. It does not screen the full US market.

Missing values

A company with no value for a filtered field is excluded from the results — absence never satisfies a clause. A company with no value for the sort field still qualifies but sorts last.

Where the values come from

Multiples and ratios are computed from SEC fundamentals and price inputs; the price analytics are Financial Data API’s own derived analytics. The screener reads the latest published value per field — it is a filter over stored values, not a live calculator.

Agent access

The MCP server exposes the screener as screen_equities, with equity_screener_fields for field discovery — the equity analogues of screen_macro and screener_fields.

Macro screener

The cross-country original: same DSL, canonical macro indicators as fields.

Derived analytics

The valuation multiples and price analytics behind the screenable fields.

Companies

The scored universe the screener evaluates.

Financial statements

The SEC fundamentals underneath the multiples and ratios.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Equity screener

How it works

Parameters

Screenable fields

Discovering fields

Running a screen

The response

Authentication

Notes and caveats

Macro screener

Derived analytics

Companies

Financial statements

​How it works

​Parameters

​Screenable fields

​Discovering fields

​Running a screen

​The response

​Authentication

​Notes and caveats

​Related

Macro screener

Derived analytics

Companies

Financial statements

How it works

Parameters

Screenable fields

Discovering fields

Running a screen

The response

Authentication

Notes and caveats

Related