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

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:

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

{
  "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:

Name
missing_input_behavior
Type
string
Description
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.
Name
denominator_zero_behavior
Type
string | null
Description
How a ratio behaves when its denominator is zero. null on a metric that has no denominator.
Name
market_data_required
Type
boolean
Description
true for metrics needing a price input. These depend on market data being present for the period, not only on the filing.
Name
unit_type
Type
string
Description
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 hold.
Derived metrics are computed from canonical ones. GROSS_MARGIN, ROE, ROIC, FCF_CONVERSION. These live on the modeling and derived-metric routes.

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:

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:

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:

{
  "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 takes.

Views are the wider equivalent, mixing canonical and derived metrics for a modeling use case:

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:

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.

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

Resolve tickers to full issuer records, search by name, and read mapping validity.

Time series

Pull a metric across a whole reporting history, point-in-time or as-reported.

Modeling

Snapshot-anchored ratios, growth, TTM aggregates and normalized model periods.