---
title: "Get axis-grouped dimensional breakdown for an entity"
method: GET
path: "/api/v1/entities/{entity_id}/financials/breakdown"
tags: ["Financials"]
---

# Get axis-grouped dimensional breakdown for an entity

`GET /api/v1/entities/{entity_id}/financials/breakdown`

## Request

- Base URL: `https://api.hub-equity.com`
- URL: `https://api.hub-equity.com/api/v1/entities/{entity_id}/financials/breakdown`
- Auth: HTTP bearer

Returns the dimensional decomposition of a metric grouped by XBRL axis. Includes reconciliation (sum_to_consolidated) and is_additive flag. Without the `facts.premium` scope, the axes are listed with their consolidated totals but `members` is empty.

`metric` is OPTIONAL. Omit it to let the service elect one it can actually render (`metric_selection=auto_selected`). Supply it and it is **never** replaced by another: an entity that does not tag that metric dimensionally yields the same metric with `axes: []` and `metric_selection=requested_not_dimensional`, and `available_metrics` lists what it does tag. Read `metric_selection`, not just `metric`.

## Path parameters

- `entity_id` string, required

## Query parameters

- `metric` string, nullable: Hub concept code. Omit to let the service elect a renderable one. A supplied code is served or reported as non-dimensional, never swapped for another.
- `years` integer: Lookback period
- `fiscal_year` integer, nullable: Optional single fiscal year

## Response `200`

Successful Response

- ApiResponseBreakdownResponse
  - `success` boolean, required
  - `data` BreakdownResponse: Axis-grouped breakdown. Members are grouped by XBRL axis rather than returned as one flat list.
    - `entity_id` string, required
    - `entity_name` string, required
    - `metric` string, required
    - `requested_metric` string, nullable
    - `metric_selection` 'as_requested' | 'auto_selected' | 'requested_not_dimensional' | 'none_available'
    - `metric_label` string, required
    - `metric_data_type` string, nullable
    - `currency` string, nullable, required
    - `available_metrics` AvailableMetric[], required
      - `code` string, required
      - `label` string, required
      - `category` string, required
      - `axis_count` integer, required
      - `member_count` integer, required
      - `primary` boolean
    - `consolidated` object, required
    - `trend_consolidated` object
    - `consolidated_derived` object
    - `axes` BreakdownAxis[], required
      - `axis_qname` string, required
      - `axis_label` string, required
      - `axis_kind` string, required
      - `members` BreakdownMember[], required
        - `member_qname` string, required
        - `member_label` string, required
        - `values` object, required
        - `currency` string, nullable, required
        - `parent_member_qname` string, nullable
        - `level` integer
        - `reconciliation_role` string, nullable
      - `is_additive` boolean, required
      - `sum_to_consolidated` object, required
      - `as_filed_total` object
      - `served_total` object
      - `reconciliation_basis` string
      - `currencies` string[]
      - `is_multi_currency` boolean
      - `disclosure_filing_id` string, nullable
      - `disclosure_link_role` string, nullable
      - `reconciliation` ReconciliationSummary: Server-side reconciliation arithmetic for a ConsolidationItems axis. Each scalar is a per-fiscal-year map, so a client can switch the selected year without re-querying. Computed deterministically: buildup_total = Σ values of buildup members (segment contributions carried via the sibling BusinessSegments axis) bridge_total = Σ values of bridge members (with sign flipped when XBRL stores a deduction as positive — the canonical Apple CorporateNonSegmentMember case) total = consolidated value of the metric for the period Invariant per year (within 1% tolerance): buildup_total + bridge_total ≈ total
        - `total` object
        - `buildup_total` object
        - `bridge_total` object
        - `is_balanced` boolean
      - `has_structural_sign_error` boolean
      - `partition_key` string, nullable
      - `partition_label` string, nullable
    - `fiscal_years` integer[], required
    - `twin_provenance` BreakdownTwinProvenance: Where a European page's business breakdown comes from. The page's own filings (ESEF) carry no business axis; the same issuer's SEC filings (20-F / 40-F) do. Members are served under THIS page's consolidated totals only for the (hub, year) couples where the twin's served total agrees with this page's within ``tolerance``; the others are listed in ``dropped``.
      - `twin_entity_id` string, required
      - `twin_entity_name` string, required
      - `twin_form_type` string, nullable
      - `twin_standard` 'ifrs' | 'us-gaap' | 'mixed', nullable
      - `twin_url` string, required
      - `tolerance` number, required
      - `hub_years_served` integer, required
      - `dropped` BreakdownTwinDrop[]
        - `hub_concept_code` string, required
        - `fiscal_year` integer, required
        - `reason` string, required
        - `page_total` number, nullable
        - `twin_total` number, nullable
  - `error` ApiError: API error details.
    - `code` string, required
    - `message` string, required
    - `details` object, nullable
  - `meta` ApiMeta: API response metadata. Pagination fields (``page`` / ``per_page`` / ``total``) are populated on collection endpoints only. They are omitted from the payload on single-resource endpoints.
    - `timestamp` string, date-time
    - `request_id` string, nullable
    - `page` integer, nullable
    - `per_page` integer, nullable
    - `total` integer, nullable
  - `links` ApiLinks: HATEOAS-style pagination cursors. Host-relative path + query links for a collection page. Present on collection endpoints, ``null`` fields where a page doesn't exist (``next`` on the last page, ``prev`` on the first). The whole ``links`` object is omitted from single-resource responses (see ``ApiResponse`` serializer).
    - `self` string, nullable
    - `first` string, nullable
    - `prev` string, nullable
    - `next` string, nullable
    - `last` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/hub-equity/apis/hub-equity-api.md) · [All operations](https://skmtc.dev/hub-equity/apis/hub-equity-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hub-equity/apis/hub-equity-api/revisions/e8eeda5dc13e?raw)