# Metric catalog Metric names are part of the wire contract, and the canonical set is not the same as the derived set: a name valid on one route is refused on another. The catalog tells you which is which before you query, and lets you validate names locally instead of discovering the problem one request at a time. ## Check the name first ```bash curl -X GET "https://api.arche.fi/v1/metrics/definitions" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` 132 canonical definitions come back in one call, so fetch it once at startup and validate names locally rather than discovering the problem per query. For one metric: ```bash curl -X GET "https://api.arche.fi/v1/metrics/definitions/REVENUE" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` ## Metric definitions ```json { "data": [ { "metric": "ACCOUNTS_PAYABLE", "display_name": "Accounts payable", "category": "LIABILITIES", "statement_type": "BALANCE_SHEET", "is_canonical": true, "is_derived": false, "unit_type": "currency", "formula": "normalized_edgar_mapping", "dependencies": [], "denominator_zero_behavior": null, "missing_input_behavior": "null_if_metric_not_available", "market_data_required": false, "source_notes": "Canonical EDGAR metric derived from normalized XBRL mapping rules." } ] } ``` Four fields are worth reading before you use a metric in a calculation: - `missing_input_behavior` (string): What the metric does when an input is absent. `null_if_metric_not_available` means you get `null` rather than a zero, so an absent figure never silently becomes a real one. - `denominator_zero_behavior` (string | null): How a ratio behaves when its denominator is zero. `null` on a metric that has no denominator. - `market_data_required` (boolean): `true` for metrics needing a price input. These depend on market data being present for the period, not only on the filing. - `unit_type` (string): `currency`, `ratio`, `shares` and similar. It tells you whether a value is an amount, a proportion, or a count before you format it. ## Canonical vs derived This distinction decides which routes will answer for a name: - **Canonical** metrics (`is_canonical: true`, `is_derived: false`) are mapped straight from XBRL tags. `REVENUE`, `NET_INCOME`, `TOTAL_ASSETS`, `GROSS_PROFIT`. These are what statements, time series and [coverage](https://docs.arche.fi/coverage) hold. - **Derived** metrics are computed from canonical ones. `GROSS_MARGIN`, `ROE`, `ROIC`, `FCF_CONVERSION`. These live on the [modeling](https://docs.arche.fi/modeling) and derived-metric routes. > **Note:** Asking a canonical-metric route for a derived name is refused with > `400 VALIDATION_ERROR`, and the message lists the canonical > names that route accepts. `/v1/coverage/metrics/GROSS_MARGIN` > answers that way because `GROSS_MARGIN` is derived, not because > no company has a gross margin. Read `is_derived` here to know > which route to ask. ## Derived metric catalog The derived metrics and their formulas: ```bash curl -X GET "https://api.arche.fi/v1/edgar/derived-metrics/catalog" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` Read `dependencies` on a derived metric to see which canonical metrics it needs. If one of those is absent for a period, the derived metric will be absent too — which is why a derived series can have gaps a canonical series does not. ## Bundles and views Curated metric groupings, so you can request a coherent set without naming every member: ```bash curl -X GET "https://api.arche.fi/v1/edgar/metric-bundles" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` Representative response: ```json { "data": [ { "code": "cash_flow_quality", "label": "Cash flow quality", "description": "Filing-based cash-flow quality metrics only.", "metrics": ["CFO_TO_NET_INCOME", "FCF_CONVERSION", "CFO_MARGIN", "FCF_MARGIN"] }, { "code": "core_balance_sheet", "label": "Core balance sheet", "description": "Canonical filing-based balance-sheet metrics.", "metrics": [ "CASH_AND_CASH_EQUIVALENTS", "TOTAL_ASSETS", "TOTAL_LIABILITIES", "TOTAL_EQUITY" ] } ] } ``` Eight bundles exist. A bundle `code` is what [`/v1/edgar/companies/{cik}/metric-bundles/{bundle_code}/time-series`](https://docs.arche.fi/time-series) takes. Views are the wider equivalent, mixing canonical and derived metrics for a modeling use case: ```bash curl -X GET "https://api.arche.fi/v1/views/metrics" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` `core_fundamentals` is the broad one, carrying margins, growth, cash flow, capital structure and returns together. Request a single view by code at `/v1/views/metrics/{bundle_code}`. ## Segments Dimensional breakdowns — the segment, geography and product axes a filer tagged its facts along: ```bash curl -X GET "https://api.arche.fi/v1/metrics/segments?cik=0000789019&page_size=50" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` Each row carries a `metric_dimension_id` and the `statement_version_id` it belongs to, so a segment figure is anchored to the same statement version as the consolidated one. Filter by `cik`, `company_id`, `period` or `dimension_type`. > **Note:** Segment rows are dimensional facts, not a separate statement. A segment > total and the consolidated figure come from the same filing, so they > reconcile — but only within one `statement_version_id`. Do not > mix a segment row from one version with a consolidated figure from another. ## Next steps - [Company identity](https://docs.arche.fi/identity): Resolve tickers to full issuer records, search by name, and read mapping validity. - [Time series](https://docs.arche.fi/time-series): Pull a metric across a whole reporting history, point-in-time or as-reported. - [Modeling](https://docs.arche.fi/modeling): Snapshot-anchored ratios, growth, TTM aggregates and normalized model periods.