# Computed metrics

82 metrics computed from each filing (margins, growth, leverage, efficiency, cash flow, valuation), each with its formula and the facts it used. US companies only. Starter plan or higher; formula_override needs Pro.

| MCP tool | CLI command |
|---|---|
| `akkru_metrics` | `akkru metrics` |

## Actions

| Action | What it does |
|---|---|
| `get` | One filing's metrics. Name the filing with metric_group_id, filing_id, or ticker and fiscal_year. All metrics by default; metric_names for chosen ones; category for one of six groups. Price-based ratios come at the filing-date price, and also at current_price when you give it; filing_date_price_only skips the current-price block. 158 credits. |
| `history` | The same metrics over many periods for one ticker, newest or oldest first, up to 5 periods per page. 55 credits plus 148 per period on the page. |
| `list` | A company's filings that have metrics, with their metric_group_id; give fiscal_year or as_of_date. 10 credits. |
| `catalog` | Every metric name with its unit, plus the operators and options search takes. Free. |
| `search` | Screen every covered company with conditions on metrics (where). Pro plan or higher; 89-1,825 credits depending on the conditions; the response shows the price. |

Metric names are catalog ids such as gross_margin; a wrong name returns the full list of names.

## Parameters

| Parameter | Type | Actions | Description |
|---|---|---|---|
| `metric_group_id` | integer | `get` | Metric set id from action "list". One of metric_group_id, filing_id, or ticker with fiscal_year names the filing. |
| `filing_id` | integer | `get` | Filing id from the `list` action of [Filings](/documents/filings.md). One of metric_group_id, filing_id, or ticker with fiscal_year names the filing. |
| `ticker` | string | `get`, `history`, `list` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. |
| `form_type` | string | `get` | Form, default "10-K": "10-K" or "10-Q" for US filers, "20-F" or "40-F" for foreign issuers filing with the SEC. Korean, Japanese, Chinese and European filings use "10-K" for annual and "10-Q" for interim reports. |
| `fiscal_year` | integer | `get`, `list` | Fiscal year of the filing (1990-2100). |
| `quarter` | string | `get`, `list` | "FY", "Q1", "Q2", "Q3" or "Q4". list: filters the list, omit for every quarter; get: needed only when the fiscal year has several filings of the form; the error then lists the quarters on file. |
| `form_types` | array of string | `list` | Forms to include, e.g. ["10-K", "10-Q"] (up to 8). Default: every form. |
| `metric_names` | array of string | `get`, `history` | Metric ids, e.g. ["gross_margin", "pe_ratio"]. get: only these; history: only these (default all). The names are in action "catalog". |
| `category` | string | `get` | One group of metrics: profitability, growth, financial_health, efficiency, cash_flow or valuation. |
| `filing_date_price_only` | boolean | `get` | true: price-based ratios at the filing-date price only, without the current-price block; with all metrics or with category valuation. |
| `current_price` | number | `get` | Current share price in USD; price-based ratios are then also computed at it (above 0, at most 10,000,000, at most 4 decimals). Without it the current-price block says it is missing. |
| `current_fx_rate` | number | `get` | Fallback exchange rate, used only when the current rate for a foreign-currency filing is briefly unavailable (above 0, at most 1,000,000, at most 6 decimals). |
| `accept_suggested_formula` | boolean | `get`, `history` | true: compute the metrics that need a formula choice with the suggested formula. |
| `formula_override` | object | `get`, `history` | Your own formula per metric id, e.g. {"interest_coverage": {"concepts": ["OperatingIncomeLoss", "InterestExpense"], "operators": ["/"]}}. Pro plan or higher. |
| `as_of_date` | string | `get`, `history`, `list`, `search` | Date "YYYY-MM-DD": only what had been filed by that day counts. Default: no cutoff. |
| `period_type` | string | `history` | "quarterly" (default) or "annual". annual covers 10-K, 20-F and 40-F; quarterly covers 10-Q. |
| `start_period_start` | string | `history` | Earliest period start, "YYYY-MM-DD". |
| `end_period_end` | string | `history` | Latest period end, "YYYY-MM-DD". |
| `sort` | string | `history` | "period_end_asc" (default) or "period_end_desc". |
| `page` | integer | `history`, `search` | Page number, from 1; the response's next_page gives the next one. |
| `page_size` | integer | `history`, `search` | history: periods per page, 1-5 (default 3); search: rows per page, 1-100 (default 50), with page times page_size at most 500. |
| `where` | object | `search` | Conditions and sort: {"filter": <tree>, "sort_by"?: <metric id, or "ticker", "period_end", "filing_date", "match_count">, "sort_order"?: "asc" or "desc"}. A tree is a leaf {"metric": <id>, "op": ">", ">=", "<", "<=" or "between", "value": <number, or [low, high] for between>} with at most one of "for_latest", "for_consecutive", "for_at_least": N; or {"and": [...]}, {"or": [...]}, {"not": <tree>}. 1-10 leaves, nesting depth at most 4. |
| `lookback` | integer | `search` | How many filings back the conditions look (1-120, default 1); cut to your plan's history window. |
| `include_quarterly` | boolean | `search` | true: quarterly filings count too; default annual only. |
| `tickers` | array of string | `search` | Only these companies (up to 100); any symbol a company has traded under. Default: every company. |
| `exclude_tickers` | array of string | `search` | Leave these companies out (up to 100). |
| `usd_only` | boolean | `search` | true: only rows whose values are in USD. |
| `sectors` | array of string | `search` | Only companies in these sectors (names from the `catalog` action of [Computed metrics](/documents/computed-metrics.md)). Pro plan or higher. |
| `include_metrics_using_filing_date_price` | boolean | `search` | false: the 13 price-based valuation ratios cannot be used in conditions or sorting; default true. |
| `exclude_derivations` | array of string | `search` | Conditions ignore metric values derived these ways, e.g. "composite" (the kinds are in action "catalog"). |
| `include_metrics` | array of string | `search` | Extra metric ids to return next to the ones in the conditions (up to 10). |
| `group_by_ticker` | boolean | `search` | true (default): one row per company; false: one row per filing. |
| `detail` | string | every action | Response detail, same price at every level: "full" (default) returns everything; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns only the values and what identifies them, without sources or calculation details. Every action takes it; a call without detail levels ignores it. Try "light" or "minimal" for shorter replies that use less context and fewer tokens. One of `full`, `light`, `minimal`. |

## Examples

```json title="MCP"
{"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "category": "profitability"}
```

```bash title="CLI"
akkru metrics get --ticker AAPL --fiscal-year 2025 --category profitability
```

```json title="MCP"
{"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "metric_names": ["gross_margin", "pe_ratio"]}
```

```bash title="CLI"
akkru metrics get --ticker AAPL --fiscal-year 2025 --json '{"metric_names": ["gross_margin", "pe_ratio"]}'
```

```json title="MCP"
{"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "filing_date_price_only": true}
```

```bash title="CLI"
akkru metrics get --ticker AAPL --fiscal-year 2025 --filing-date-price-only
```

```json title="MCP"
{"action": "history", "ticker": "AAPL", "period_type": "annual", "metric_names": ["gross_margin"], "page_size": 5}
```

```bash title="CLI"
akkru metrics history --ticker AAPL --period-type annual --page-size 5 --json '{"metric_names": ["gross_margin"]}'
```

```json title="MCP"
{"action": "list", "ticker": "AAPL", "fiscal_year": 2025}
```

```bash title="CLI"
akkru metrics list --ticker AAPL --fiscal-year 2025
```

```json title="MCP"
{"action": "catalog"}
```

```bash title="CLI"
akkru metrics catalog
```

```json title="MCP"
{"action": "search", "where": {"filter": {"metric": "return_on_equity", "op": ">", "value": 0.2, "for_latest": 3}}, "lookback": 3, "page_size": 10}
```

```bash title="CLI"
akkru metrics search --lookback 3 --page-size 10 --json '{"where": {"filter": {"metric": "return_on_equity", "op": ">", "value": 0.2, "for_latest": 3}}}'
```