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

## 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 akkru_filings action "list". 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 akkru_metrics action "catalog"). 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 | `get`, `history`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. |

## Examples

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

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

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

```json
{"action": "catalog"}
```

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