> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Equity screener

> Screen the scored US equity universe (S&P 500 union Nasdaq-100) by valuation multiples, financial ratios, and price analytics with the compact filter DSL.

The equity screener is the company-level counterpart of the [macro screener](/guides/screener). Instead of filtering countries by indicator values, you filter the [scored universe](/apis/companies) 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."

<Note>
  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](/apis/derived-analytics). It never exposes internal scoring and never touches licensed data.
</Note>

## 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:

```text theme={"theme":"css-variables"}
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:

```text theme={"theme":"css-variables"}
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.                                     |

<Warning>
  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.
</Warning>

## 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.

<AccordionGroup>
  <Accordion title="Classification and size" icon="sitemap">
    `sector`, `industry` (string; `eq`/`in`, case-insensitive), `market_cap`.
  </Accordion>

  <Accordion title="Valuation multiples (13)" icon="scale-balanced">
    `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`.
  </Accordion>

  <Accordion title="Financial ratios (10)" icon="percent">
    `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`.
  </Accordion>

  <Accordion title="Price analytics (8)" icon="chart-line">
    `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`.
  </Accordion>
</AccordionGroup>

### Discovering fields

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

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/public/equity-screener/filters" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  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);
  }
  ```
</CodeGroup>

<Tip>
  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`.
</Tip>

## Running a screen

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

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  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"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  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);
  }
  ```
</CodeGroup>

### 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:

```json Response theme={"theme":"css-variables"}
{
  "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": "..."
}
```

<Note>
  Example values above are illustrative. Run the screen for live results.
</Note>

## Authentication

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

## Notes and caveats

<AccordionGroup>
  <Accordion title="The universe">
    The screener evaluates the scored universe — S\&P 500 union Nasdaq-100, the same membership as [`GET /companies`](/apis/companies). It does not screen the full US market.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/apis/derived-analytics). The screener reads the latest published value per field — it is a filter over stored values, not a live calculator.
  </Accordion>

  <Accordion title="Agent access">
    The [MCP server](/ai-agents/mcp-server) exposes the screener as `screen_equities`, with `equity_screener_fields` for field discovery — the equity analogues of `screen_macro` and `screener_fields`.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Macro screener" icon="filter" href="/guides/screener">
    The cross-country original: same DSL, canonical macro indicators as fields.
  </Card>

  <Card title="Derived analytics" icon="function" href="/apis/derived-analytics">
    The valuation multiples and price analytics behind the screenable fields.
  </Card>

  <Card title="Companies" icon="building" href="/apis/companies">
    The scored universe the screener evaluates.
  </Card>

  <Card title="Financial statements" icon="building-columns" href="/apis/financial-statements">
    The SEC fundamentals underneath the multiples and ratios.
  </Card>
</CardGroup>