# Stock Screener

> Filter securities by financial metrics, profile attributes, valuation multiples, stability ratios, ESG scores, and more.

`POST https://api.bavest.co/v2/reference/screener`

Group: Reference. Route id: `v2_reference_screener_post`. Included in: Growth.

## Description

Filter securities by financial metrics, profile attributes, valuation multiples, stability ratios, ESG scores, and more. All query conditions are combined with AND. Results include the requested metric values alongside each security's symbol, name, and ISIN.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

None.

## Request body

JSON, required.

| Field | Type | Always present | Description |
|---|---|---|---|
| `query` | array of ScreenerFilterItem | yes | List of filter conditions. All conditions are combined with AND logic. Each item specifies a metric, comparison operator, and threshold value. |
| `query[].metric` | string | yes | Short name for a screener metric. Resolved internally to an Elasticsearch field path. Alternatively, pass a raw dot-notation ES path directly (e.g., `profile.marketCapitalization`). Values: see `query[].metric` below. Example: `returnOnEquity`. |
| `query[].operator` | string | yes | Comparison operator. Use `eq` for exact string matches (e.g., sector, country). Numeric operators (`lt`, `gt`, `gte`, `lte`) for numeric fields. One of `lt`, `gt`, `gte`, `lte`, `eq`. Example: `gte`. |
| `query[].value` | number \| string \| boolean | yes | The value to compare against. Use a number for numeric metrics, a string for text fields (sector, country, industry, name, symbol) and a boolean for flags (`isReit`, with operator `eq`). Example: `10`. |
| `sort` | array of ScreenerSortItem | no | Optional list of sort criteria applied in order. When omitted results are returned in default Elasticsearch relevance order. |
| `sort[].metric` | string | yes | Short name for a screener metric. Resolved internally to an Elasticsearch field path. Alternatively, pass a raw dot-notation ES path directly (e.g., `profile.marketCapitalization`). Values: see `query[].metric` below. Example: `returnOnEquity`. |
| `sort[].order` | string | yes | Sort direction. One of `asc`, `desc`. Example: `desc`. |
| `offset` | integer | no | Pagination offset (number of results to skip). Example: `0`. |
| `limit` | integer | no | Maximum number of results to return. Example: `10`. |
| `currency` | string | no | Target currency for value conversion. When set, monetary metric values are converted to this currency. Example: `EUR`. |

### Values of `query[].metric`

- `name`: Company name (Category: Profile; ES Path: profile.name)
- `symbol`: Ticker symbol (Category: Profile; ES Path: profile.symbol)
- `isin`: ISIN identifier (Category: Profile; ES Path: profile.isin)
- `stockExchange`: Primary listing exchange (Category: Profile; ES Path: profile.exchangeShortName)
- `employeeTotal`: Total number of employees (Category: Profile; ES Path: profile.employeeTotal)
- `marketCapitalization`: Market cap (value x1 transform) (Category: Profile; ES Path: profile.marketCapitalization)
- `country`: Country of domicile (Category: Profile; ES Path: profile.country)
- `beta`: Beta coefficient (Category: Profile; ES Path: profile.beta)
- `industry`: Industry classification (Category: Profile; ES Path: profile.industry)
- `sector`: GICS sector (Category: Profile; ES Path: profile.sector)
- `price`: Current stock price (Category: Profile; ES Path: profile.price)
- `isReit`: REIT flag (boolean): FMP industry starts with "REIT", e.g. "REIT - Retail" (Category: Profile; ES Path: profile.isReit)
- `retainedEarnings`: Accumulated retained earnings (Category: Balance; ES Path: balance.retainedEarnings)
- `totalAssets`: Total assets (Category: Balance; ES Path: balance.totalAssets)
- `currentAssets`: Current assets (Category: Balance; ES Path: balance.currentAssets)
- `fixedAssets`: Fixed (non-current) assets (Category: Balance; ES Path: balance.fixedAssets)
- `totalCurrentLiabilities`: Total current liabilities (Category: Balance; ES Path: balance.totalCurrentLiabilities)
- `totalNonCurrentLiabilities`: Total non-current liabilities (Category: Balance; ES Path: balance.totalNonCurrentLiabilities)
- `longTermDebt`: Long-term debt (Category: Balance; ES Path: balance.longTermDebt)
- `totalLiabilities`: Total liabilities (Category: Balance; ES Path: balance.totalLiabilities)
- `totalEquity`: Total shareholders' equity (Category: Balance; ES Path: balance.totalEquity)
- `liabilitiesAndEquity`: Liabilities plus equity (Category: Balance; ES Path: balance.liabilitiesAndEquity)
- `operatingCashFlow`: Operating cash flow (Category: Cash flow; ES Path: cashflow.operatingCashFlow)
- `investingCashFlow`: Investing cash flow (Category: Cash flow; ES Path: cashflow.investingCashFlow)
- `financingCashFlow`: Financing cash flow (Category: Cash flow; ES Path: cashflow.financingCashFlow)
- `capitalExpenditure`: Capital expenditure (Category: Cash flow; ES Path: cashflow.capitalExpenditure)
- `freeCashFlow`: Free cash flow (Category: Cash flow; ES Path: cashflow.freeCashFlow)
- `netIncomeAfterTaxes`: Net income after taxes (Category: Income; ES Path: income.netIncomeAfterTaxes)
- `totalRevenue`: Total revenue (Category: Income; ES Path: income.totalRevenue)
- `grossIncome`: Gross income (Category: Income; ES Path: income.grossIncome)
- `ebit`: Earnings before interest and taxes (Category: Income; ES Path: income.ebit)
- `pretaxIncome`: Pre-tax income (Category: Income; ES Path: income.pretaxIncome)
- `ebitda`: EBITDA (Category: Income; ES Path: income.ebitda)
- `eps`: Earnings per share (Category: Income; ES Path: income.eps)
- `stockPrice`: Current stock price (quote) (Category: Quote; ES Path: quote.stockPrice)
- `shareOutstanding`: Shares outstanding (Category: Quote; ES Path: quote.shareOutstanding)
- `c`: Current price (Category: Quote; ES Path: quote.c)
- `dp`: Daily price change (%) (Category: Quote; ES Path: quote.dp)
- `environmentScore`: Environmental ESG score (Category: ESG; ES Path: esg.environmentScore)
- `governanceScore`: Governance ESG score (Category: ESG; ES Path: esg.governanceScore)
- `socialScore`: Social ESG score (Category: ESG; ES Path: esg.socialScore)
- `totalESGScore`: Combined ESG score (Category: ESG; ES Path: esg.totalESGScore)
- `dividendPerShare`: Dividend per share (Category: Metrics; ES Path: metric.dividendPerShare)
- `dividendPerShareAnnual`: Dividend per share (annual, alias) (Category: Metrics; ES Path: metric.dividendPerShare)
- `5DayPriceReturnDaily`: 5-day price return (Category: Metrics; ES Path: metric.5DayPriceReturnDaily)
- `13WeekPriceReturnDaily`: 13-week price return (Category: Metrics; ES Path: metric.13WeekPriceReturnDaily)
- `26WeekPriceReturnDaily`: 26-week price return (Category: Metrics; ES Path: metric.26WeekPriceReturnDaily)
- `52WeekPriceReturnDaily`: 52-week price return (Category: Metrics; ES Path: metric.1yearPriceReturnDaily)
- `roaRfy`: Return on assets (RFY) (Category: Metrics; ES Path: metric.roaRfy)
- `bookValuePerShareAnnual`: Book value per share (annual) (Category: Metrics; ES Path: metric.bookValuePerShareAnnual)
- `cashFlowPerShareAnnual`: Cash flow per share (annual) (Category: Metrics; ES Path: metric.cashFlowPerShareAnnual)
- `dividendYield5Y`: 5-year average dividend yield (Category: Metrics; ES Path: metric.dividendYield5Y)
- `dividendGrowthRate5Y`: 5-year dividend growth rate (Category: Metrics; ES Path: metric.dividendGrowthRate5Y)
- `epsGrowth3Y`: 3-year EPS growth (Category: Metrics; ES Path: metric.epsGrowth3Y)
- `epsGrowth5Y`: 5-year EPS growth (Category: Metrics; ES Path: metric.epsGrowth5Y)
- `capitalSpendingGrowth5Y`: 5-year capex growth (Category: Metrics; ES Path: metric.capitalSpendingGrowth5Y)
- `currentEv/freeCashFlowAnnual`: EV / FCF (annual) (Category: Metrics; ES Path: metric.currentEv/freeCashFlowAnnual)
- `currentEv/freeCashFlowTTM`: EV / FCF (TTM) (Category: Metrics; ES Path: metric.currentEv/freeCashFlowTTM)
- `revenueEmployeeAnnual`: Revenue per employee (annual) (Category: Metrics; ES Path: metric.revenueEmployeeAnnual)
- `revenueEmployeeTTM`: Revenue per employee (TTM) (Category: Metrics; ES Path: metric.revenueEmployeeTTM)
- `revenueGrowth3Y`: 3-year revenue growth (Category: Metrics; ES Path: metric.revenueGrowth3Y)
- `revenuePerShareAnnual`: Revenue per share (annual) (Category: Metrics; ES Path: metric.revenuePerShareAnnual)
- `revenuePerShareTTM`: Revenue per share (TTM) (Category: Metrics; ES Path: metric.revenuePerShareTTM)
- `revenueShareGrowth5Y`: 5-year revenue share growth (Category: Metrics; ES Path: metric.revenueShareGrowth5Y)
- `payoutRatioAnnual`: Payout ratio (annual) (Category: Metrics; ES Path: metric.payoutRatioAnnual)
- `payoutRatioTTM`: Payout ratio (TTM) (Category: Metrics; ES Path: metric.payoutRatioTTM)
- `performance`: Overall performance score (Category: Metrics; ES Path: metric.performance)
- `priceEarningsRatio`: P/E ratio (Category: Multiples; ES Path: fundamentals.multiples.priceEarningsRatio)
- `priceBookRatio`: P/B ratio (Category: Multiples; ES Path: fundamentals.multiples.priceBookRatio)
- `priceCashflowRatio`: P/CF ratio (Category: Multiples; ES Path: fundamentals.multiples.priceCashflowRatio)
- `priceSalesRatio`: P/S ratio (Category: Multiples; ES Path: fundamentals.multiples.priceSalesRatio)
- `ev/ebitda`: EV / EBITDA (Category: Multiples; ES Path: fundamentals.multiples.ev/ebitda)
- `ev/ebit`: EV / EBIT (Category: Multiples; ES Path: fundamentals.multiples.ev/ebit)
- `ev/fcf`: EV / Free Cash Flow (Category: Multiples; ES Path: fundamentals.multiples.ev/fcf)
- `ev`: Enterprise value (Category: Multiples; ES Path: fundamentals.multiples.ev)
- `ev/revenue`: EV / Revenue (Category: Multiples; ES Path: fundamentals.multiples.ev/revenue)
- `propertyPlantEquipment`: Fixed assets intensity (PP&E proxy) (Category: Multiples; ES Path: fundamentals.multiples.fixedAssetsIntensity)
- `ev/sales`: EV / Sales (Category: Multiples; ES Path: fundamentals.multiples.ev/sales)
- `equityRatio`: Equity ratio (Category: Stability; ES Path: fundamentals.stability.equityRatio)
- `debtRatio`: Total liabilities / total assets. Not total debt: `debt_to_assets` in financials.metrics is total debt / total assets (Category: Stability; ES Path: fundamentals.stability.debtRatio)
- `debtToEquityRatio`: Total liabilities / total equity. Not total debt: `debt_to_equity` in financials.metrics is total debt / total equity. Negative for negative equity, where `debt_to_equity` is null (Category: Stability; ES Path: fundamentals.stability.debtToEquityRatio)
- `dynamicLeverage`: Dynamic leverage ratio (Category: Stability; ES Path: fundamentals.stability.dynamicLeverage)
- `cataRatio`: Current assets to total assets (Category: Stability; ES Path: fundamentals.stability.cataRatio)
- `currentRatio`: Current ratio (Category: Stability; ES Path: fundamentals.stability.currentRatio)
- `fixedAssetIntensity`: Fixed asset intensity (Category: Stability; ES Path: fundamentals.stability.fixedAssetIntensity)
- `ppeRatio`: PP&E ratio (Category: Stability; ES Path: fundamentals.stability.ppeRatio)
- `assetCoverage1`: Asset coverage ratio (tier 1) (Category: Stability; ES Path: fundamentals.stability.assetCoverage1)
- `assetCoverage2`: Asset coverage ratio (tier 2) (Category: Stability; ES Path: fundamentals.stability.assetCoverage2)
- `cashRatio`: Cash ratio (Category: Stability; ES Path: fundamentals.stability.cashRatio)
- `quickRatio`: Quick ratio (Category: Stability; ES Path: fundamentals.stability.quickRatio)
- `returnOnEquity`: Return on equity (ROE) (Category: Profitability; ES Path: fundamentals.revenue.equityReturn)
- `salesReturn`: Return on sales (Category: Profitability; ES Path: fundamentals.revenue.salesReturn)
- `ebitMargin`: EBIT margin (Category: Profitability; ES Path: fundamentals.revenue.ebitMargin)
- `ebitdaMargin`: EBITDA margin (Category: Profitability; ES Path: fundamentals.revenue.ebitdaMargin)
- `capitalTurnover`: Capital turnover (Category: Profitability; ES Path: fundamentals.revenue.capitalTurnover)
- `assetsReturn`: Return on assets (Category: Profitability; ES Path: fundamentals.revenue.assetsReturn)
- `fundamentalScore`: Fundamental analysis score (Category: Scores; ES Path: score.fundamentalScore)
- `totalScore`: Composite total score (Category: Scores; ES Path: score.totalScore)
- `sentimentScore`: Market sentiment score (Category: Scores; ES Path: score.sentimentScore)

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | array of ScreenerResult | no |  |
| `data[].symbol` | string | yes | Ticker symbol. Example: `AAPL`. |
| `data[].name` | string | yes | Company name. Example: `Apple Inc`. |
| `data[].isin` | string | yes | ISIN identifier. Example: `US0378331005`. |
| `meta` | ResponseMeta | no | Response metadata for paginated endpoints. Offset pagination returns `page`/`pageSize`/`totalPages`/`totalCount`; cursor pagination returns `pageSize`/`hasMore`/`nextCursor` and `totalCount` only when known. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |
| `meta.page` | integer | no | Current page number (offset pagination) Example: `1`. |
| `meta.pageSize` | integer | no | Number of results per page. Example: `50`. |
| `meta.totalPages` | integer | no | Total number of pages (offset pagination) Example: `2`. |
| `meta.totalCount` | integer | no | Total number of results across all pages. Example: `100`. |
| `meta.hasMore` | boolean | no | Whether more results follow (cursor pagination) |
| `meta.nextCursor` | string \| null | no | Cursor for the next page (cursor pagination), null on the last page. |

## Example request

```bash
curl -X POST 'https://api.bavest.co/v2/reference/screener' \
  -H "x-api-key: $BAVEST_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"query":[{"metric":"returnOnEquity","operator":"gte","value":10},{"metric":"sector","operator":"eq","value":"Technology"},{"metric":"marketCapitalization","operator":"gte","value":1000000000}],"sort":[{"metric":"marketCapitalization","order":"desc"}],"offset":0,"limit":10}'
```

## Example response

```json
{
  "data": [
    {
      "symbol": "ASAN",
      "name": "Asana, Inc.",
      "isin": "US04342Y1047",
      "marketCapitalization": 2083961217,
      "returnOnEquity": 16.5541,
      "sector": "Technology"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalCount": 1,
    "parameters": {
      "query": [
        {
          "metric": "returnOnEquity",
          "operator": "gte",
          "value": 10
        },
        {
          "metric": "sector",
          "operator": "eq",
          "value": "Technology"
        }
      ],
      "sort": [
        {
          "metric": "marketCapitalization",
          "order": "desc"
        }
      ],
      "offset": 0,
      "limit": 10
    },
    "time": 447
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive). |
| 401 | Missing or invalid API key. |
| 404 | Resource not found. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_reference_screener_post
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt