# 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. Choose a value from the metric enum. `debtRatio` is total liabilities / total assets; `debtToEquityRatio` is total liabilities / total equity and can be negative for negative equity. These use total liabilities, unlike `debt_to_assets` and `debt_to_equity` in financials.metrics, which use total debt; `debt_to_equity` is null for negative equity. 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, the default result ordering is used. |
| `sort[].metric` | string | yes | Short name for a screener metric. Choose a value from the metric enum. `debtRatio` is total liabilities / total assets; `debtToEquityRatio` is total liabilities / total equity and can be negative for negative equity. These use total liabilities, unlike `debt_to_assets` and `debt_to_equity` in financials.metrics, which use total debt; `debt_to_equity` is null for negative equity. 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`
- `symbol`
- `isin`
- `stockExchange`
- `employeeTotal`
- `marketCapitalization`
- `country`
- `beta`
- `industry`
- `sector`
- `price`
- `isReit`
- `retainedEarnings`
- `totalAssets`
- `currentAssets`
- `fixedAssets`
- `totalCurrentLiabilities`
- `totalNonCurrentLiabilities`
- `longTermDebt`
- `totalLiabilities`
- `totalEquity`
- `liabilitiesAndEquity`
- `operatingCashFlow`
- `investingCashFlow`
- `financingCashFlow`
- `capitalExpenditure`
- `freeCashFlow`
- `netIncomeAfterTaxes`
- `totalRevenue`
- `grossIncome`
- `ebit`
- `pretaxIncome`
- `ebitda`
- `eps`
- `stockPrice`
- `shareOutstanding`
- `c`
- `dp`
- `environmentScore`
- `governanceScore`
- `socialScore`
- `totalESGScore`
- `dividendPerShare`
- `dividendPerShareAnnual`
- `5DayPriceReturnDaily`
- `13WeekPriceReturnDaily`
- `26WeekPriceReturnDaily`
- `52WeekPriceReturnDaily`
- `roaRfy`
- `bookValuePerShareAnnual`
- `cashFlowPerShareAnnual`
- `dividendYield5Y`
- `dividendGrowthRate5Y`
- `epsGrowth3Y`
- `epsGrowth5Y`
- `capitalSpendingGrowth5Y`
- `currentEv/freeCashFlowAnnual`
- `currentEv/freeCashFlowTTM`
- `revenueEmployeeAnnual`
- `revenueEmployeeTTM`
- `revenueGrowth3Y`
- `revenuePerShareAnnual`
- `revenuePerShareTTM`
- `revenueShareGrowth5Y`
- `payoutRatioAnnual`
- `payoutRatioTTM`
- `performance`
- `priceEarningsRatio`
- `priceBookRatio`
- `priceCashflowRatio`
- `priceSalesRatio`
- `ev/ebitda`
- `ev/ebit`
- `ev/fcf`
- `ev`
- `ev/revenue`
- `propertyPlantEquipment`
- `ev/sales`
- `equityRatio`
- `debtRatio`
- `debtToEquityRatio`
- `dynamicLeverage`
- `cataRatio`
- `currentRatio`
- `fixedAssetIntensity`
- `ppeRatio`
- `assetCoverage1`
- `assetCoverage2`
- `cashRatio`
- `quickRatio`
- `returnOnEquity`
- `salesReturn`
- `ebitMargin`
- `ebitdaMargin`
- `capitalTurnover`
- `assetsReturn`
- `fundamentalScore`
- `totalScore`
- `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://docs.bavest.co/docs/v2_reference_screener_post
- OpenAPI: https://docs.bavest.co/openapi.json (YAML: https://docs.bavest.co/openapi.yaml)
- Authentication: https://docs.bavest.co/docs/authentication.md
- MCP server for AI agents: https://docs.bavest.co/docs/mcp.md
- All routes: https://docs.bavest.co/llms.txt
