# Equity Metric Names

> Returns registered equity metric names with their unit, description and -- per name -- which reporting bases GET /equities/metrics/history can actually serve.

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

Group: Equities. Route id: `v2_equities_metrics_names`. Free in every plan, including the trial.

## Description

Returns registered equity metric names with their unit, description and -- per name -- which reporting bases GET /equities/metrics/history can actually serve. Every name here is available as a latest value on GET /equities/metrics; `bases` is narrower, because history is materialized per basis. Filter with `hasHistory` or `basis` to get only the names a history integration can rely on. No security identifier required.

## 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 |
|---|---|---|---|---|
| `hasHistory` | query | boolean | no | When true, return only names with at least one materialized basis; when false, only names without one. Omit for all names. |
| `basis` | query | string | no | Return only names materialized on this reporting basis. A basis that is valid but not yet materialized returns an empty list with count 0 rather than an error, mirroring how the history endpoint answers with a warning instead of a 404. One of `FY`, `Q1`, `Q2`, `Q3`, `Q4`, `H1`, `H2`, `TTM`. |

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.count` | integer | no | Number of metric names in this response, after any hasHistory/basis filter. Example: `103`. |
| `data.metrics` | array of object | no |  |
| `data.metrics[].name` | string | no | Canonical metric name (snake_case) Example: `pe_ratio`. |
| `data.metrics[].unit` | string | no | Unit type for the metric. Example: `ratio`. |
| `data.metrics[].description` | string | no | Human-readable description of the metric. Example: `Price-to-Earnings Ratio (P/E)`. |
| `data.metrics[].bases` | array of string | no | Reporting bases GET /equities/metrics/history can serve for this name. Empty means the name has a latest value but no history yet. A *_ttm name carries TTM and nothing else, since no other basis exists for it. |
| `data.metrics[].hasHistory` | boolean | no | Convenience flag, true exactly when `bases` is non-empty. Example: `true`. |
| `meta` | ResponseMeta | no | Response envelope metadata. Always present on a 200: `time` is set by `core/response.py` on every successful response. Errors carry the same block, built by the same code, so a client parses one meta shape whether the call succeeded or failed. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl 'https://api.bavest.co/v2/equities/metrics/names' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "count": 192,
    "metrics": [
      {
        "name": "10y_dividend_growth",
        "unit": "percentage",
        "description": "Dividend Growth (10Y)",
        "bases": [],
        "hasHistory": false
      },
      {
        "name": "10y_equity_growth",
        "unit": "percentage",
        "description": "Equity Growth (10Y)",
        "bases": [
          "FY"
        ],
        "hasHistory": true
      }
    ]
  },
  "meta": {
    "time": 2106
  }
}
```

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