# Comprehensive Metrics

> Returns comprehensive per-metric financial data with validity flags, descriptions, and units.

`GET https://api.bavest.co/v2/equities/metrics`

Group: Equities. Route id: `v2_equities_metrics`. Included in: Startup, Pro, Growth.

## Description

Returns comprehensive per-metric financial data with validity flags, descriptions, and units. Supports optional currency conversion. Results are paginated (default 50 metrics per page, max 200).

## Migrating from Stock Metric and Stock Fundamentals

Use `GET /v2/equities/metrics` when moving financial metrics and fundamental ratios from Stock Metric or Stock Fundamentals. Applications using `POST /v0/stock/metric` or `POST /v0/stock/fundamentals` need an updated request and response parser.

Provide exactly one query identifier: `symbol` or `isin`. For example, request `GET /v2/equities/metrics?symbol=AAPL&limit=50&offset=0`, omit `isin`, and send your key in the `x-api-key` header. Identifiers and filters belong in the query string rather than a legacy POST body. Set `currency` explicitly when monetary values need currency conversion.

Discover available metrics and their descriptions through [Equity Metric Names](https://docs.bavest.co/docs/v2_equities_metrics_names). The optional `fields` filter selects comma-separated `metricId` values, not arbitrary response property names. Check the IDs in the current metrics response before adding a filter; unsupported IDs can produce an empty metrics list. Do not assume every legacy metric or label has an equivalent.

Read the JSON response example below when updating your parser:

- Entries are in `data.metrics`, an array. Match each entry by `metricId` rather than relying on its position or expecting the old flat object.
- Read each entry's `value`, `valid`, `reason` and `rootCause`. Preserve `null` values instead of converting missing data to zero.
- Check the entry's `date`, `unit` and `currency` before comparing values. `data.latestDate` is the most recent date across the metrics; individual observations can have different dates.

Fetch all pages you need: `limit` defaults to 50 and is capped at 200. With offset pagination, advance `offset` and use `meta.totalCount` to track completeness. With cursor pagination, follow `meta.nextCursor` while `meta.hasMore` is true; a supplied `cursor` takes precedence over `offset`. The first page is not necessarily the complete metric set.

For historical observations, use [Equity Metric History](https://docs.bavest.co/docs/v2_equities_metrics_history) and check the supported history bases in Metric Names. For complete financial statements, use [Income Statements](https://docs.bavest.co/docs/v2_equities_income_statement), [Balance Sheets](https://docs.bavest.co/docs/v2_equities_balance_sheets) and [Cash Flow Statements](https://docs.bavest.co/docs/v2_equities_cash_flow).

Build a mapping for the legacy fields your application actually uses, and compare matching dates, units and currencies before replacing calculations. Moving documentation to Equity Metrics does not make the old API URL, field names or calculation results automatically compatible.

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

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `symbol` | query | string | one of symbol, isin | Stock ticker symbol (e.g., `AAPL`, `MSFT`, `GOOGL`). Provide exactly one of symbol or isin. Example `AAPL`. |
| `isin` | query | string | one of symbol, isin | ISIN code (e.g., `US0378331005`). Provide exactly one of symbol or isin. Clear the symbol example before using an ISIN. |
| `currency` | query | string | no | Target currency for monetary values (ISO 4217). Converts from reporting currency if different. Example when explicitly filtering: `USD`. |
| `fields` | query | string | no | Comma-separated list of metric ids to return. Unlike the statement endpoints, this filters metrics by `metricId`, not by response key. Valid ids are served by `/v2/equities/metrics/names`. Ids that do not exist match nothing, so the metrics list comes back empty. Example when explicitly filtering: `market_cap,roe_ttm`. |
| `limit` | query | integer (int32) | no | Maximum number of metrics to return per page (default 50, max 200) Default `50`. |
| `offset` | query | integer (int32) | no | Number of metrics to skip for pagination (default 0) Default `0`. |
| `cursor` | query | string | no | Opaque cursor for cursor-based pagination. When provided, returns results after the cursor position. Takes precedence over offset. |

Required: one of `symbol`, `isin`.

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | EquityMetrics | no | Comprehensive equity metrics response with per-metric metadata. |
| `data.latestDate` | string (date) \| null | no | Most recent observation date across all metrics. Example: `2025-09-27`. |
| `data.metrics` | array of object | no | Array of individual metric entries. |
| `data.metrics[].metricId` | string | no | Metric identifier (camelCase) Example: `peRatio`. |
| `data.metrics[].date` | string (date) \| null | no | Observation date of this metric value. Example: `2025-09-27`. |
| `data.metrics[].metricName` | string | no | Raw metric name from the data source. Example: `pe_ratio`. |
| `data.metrics[].value` | number (double) \| null | no | Metric value (null if unavailable) Example: `32.13`. |
| `data.metrics[].valid` | boolean | no | Whether the metric value is available. Example: `true`. |
| `data.metrics[].reason` | string \| null | no | Reason if value is null or flagged. |
| `data.metrics[].rootCause` | string \| null | no | Root cause for null or anomalous values. |
| `data.metrics[].description` | string \| null | no | Human-readable metric description. Example: `Price to earnings ratio`. |
| `data.metrics[].unit` | string \| null | no | Metric unit (e.g., ratio, USD, percent) Example: `ratio`. |
| `data.metrics[].currency` | string \| null | no | Currency of monetary values (ISO 4217) Example: `USD`. |
| `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 'https://api.bavest.co/v2/equities/metrics?symbol=AAPL' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "latestDate": "2026-10-02",
    "metrics": [
      {
        "metricId": "10y_dividend_growth",
        "metricName": "10y_dividend_growth",
        "value": 85.8023,
        "date": "2025-09-27",
        "valid": true,
        "reason": null,
        "rootCause": null,
        "description": "Dividend Growth (10Y) = (dps_last - dps_first) / |dps_first| * 100",
        "unit": "PERCENTAGE",
        "currency": "USD"
      },
      {
        "metricId": "10y_equity_growth",
        "metricName": "10y_equity_growth",
        "value": -38.2238,
        "date": "2025-09-27",
        "valid": true,
        "reason": null,
        "rootCause": null,
        "description": "Equity Growth (10Y) = (equity_last - equity_first) / |equity_first| * 100",
        "unit": "PERCENTAGE",
        "currency": "USD"
      }
    ]
  },
  "meta": {
    "page": 1,
    "pageSize": 50,
    "totalPages": 4,
    "totalCount": 189,
    "parameters": {
      "limit": "50",
      "symbol": "AAPL"
    },
    "time": 70
  }
}
```

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