---
title: "Decompose a fact into rollup + linkbase + dimensional layers"
method: GET
path: "/api/v1/entities/{entity_id}/decomposition"
tags: ["Entities"]
---

# Decompose a fact into rollup + linkbase + dimensional layers

`GET /api/v1/entities/{entity_id}/decomposition`

## Request

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

Combines three layers of granularity for one fact in a single round-trip :
- the **parent** fact (same shape as `/facts/{code}`),
- the **XBRL calculation linkbase** children for the source filing (tree walked up to `depth`, per-filing forward provenance),
- the **dimensional breakdown** (axis/member) of the same XBRL fact.

Provide EITHER `hub_concept_code` (Hub-Equity standardized) OR `qname` (raw XBRL, e.g. `us-gaap:DeferredRevenueNoncurrent`) — both are query params. `depth` 1-3 (default 1) walks the calc tree ; `depth=2` is recommended so the breakdown lands in one call.

**Premium layer**: the signed components Hub-Equity uses for this figure (`rollup_children`) are returned only with the `facts.premium` scope (as for `/filings/{id}/calculation-tree`), and so are the dimensional members; other callers get the parent and the linkbase layer, with `rollup_children` and `dimensional_breakdown` empty + a note.

## Path parameters

- `entity_id` string, required

## Query parameters

- `fiscal_year` integer, required: Fiscal year (e.g. 2024).
- `hub_concept_code` string, nullable: Hub concept code (e.g. REVENUE). Provide this OR `qname`.
- `qname` string, nullable: Raw XBRL qname (e.g. us-gaap:DeferredRevenueNoncurrent) for concepts without a hub mapping. Provide this OR `hub_concept_code`.
- `fiscal_period_type` string: FY (default, annual), Q1-Q4, or H1/H2.
- `depth` integer: Calc-linkbase tree depth (1-3, default 1). 2 is recommended for typical decomposition questions.

## Response `200`

The decomposition (parent + 3 layers).

- ApiResponseDecomposition
  - `success` boolean, required
  - `data` Decomposition: Result of `get_fact_decomposition` - combines 3 layers of granularity.
    - `parent` Fact, required: A single normalized fact returned by `get_fact`.
      - `entity_id` string, required
      - `entity_name` string, required
      - `hub_code` string, required
      - `hub_label` string, required
      - `statement` string, nullable
      - `value` number, nullable
      - `value_text` string, nullable
      - `currency` string, nullable
      - `period_start` string, nullable
      - `period_end` string, required
      - `fiscal_year` integer, nullable
      - `fiscal_period` string, nullable
      - `fiscal_period_type` string, nullable
      - `period_type` string, nullable
      - `source_concept` string, nullable: Original XBRL qname
      - `source` Source, required: Filing source for a fact (always attached so the LLM can cite). `anchor` says what kind of number this is: `tagged` (read off one tag of the issuer) or `derived` (computed by Hub-Equity from several tags, so no single place in the document holds it, by construction). `fact_url` opens the issuer's own document AT the tagged number (the iXBRL element id, resolved in the filing that SERVES the value, which is not always the filing of that fiscal year); it is served by `get_fact` and on the parent of `get_fact_decomposition`, and left empty by `get_metric_history`, whose points carry `anchor` only: one `get_fact` call gives the deep link of the point to cite.
        - `filing_id` string, required
        - `form_type` string, nullable
        - `filing_date` string, nullable
        - `period_end` string, nullable
        - `viewer_url` string, required: Hub-Equity deep link to the filing
        - `external_url` string, nullable: Original filing URL (e.g. SEC EDGAR viewer) when available
        - `anchor` 'tagged' | 'derived', nullable: tagged = the value is one tag of the issuer's document; derived = computed by Hub-Equity from several tags, no single anchor exists by construction
        - `fact_url` string, nullable: The issuer's document opened AT the tagged number (iXBRL viewer anchored on the fact id), served by get_fact and the decomposition parent when the id resolved in the serving filing; empty on history points: call get_fact for the year to cite
      - `is_restated` boolean
      - `as_filed_value` number, nullable: Always the value as printed in the filing cited by `source`; equals `value` unless `is_restated`
      - `restatement_delta_pct` number, nullable
    - `rollup_children` RollupChild[], required: The signed components of this figure for this entity (Pro)
      - `hub_code` string, required
      - `label` string, nullable
      - `sign` string, required: '+' or '-'
      - `value` number, nullable
      - `currency` string, nullable
    - `linkbase_children` LinkbaseChild[], required: XBRL calculation linkbase children (filing-specific)
      - `qname` string, required
      - `label` string, nullable
      - `weight` number, nullable
      - `corrected_weight` number, nullable
      - `order_index` number, nullable
      - `value` number, nullable
      - `unit` string, nullable
      - `fact_url` string, nullable: The issuer's document opened at this child's tagged number
      - `children` LinkbaseChild[]
    - `dimensional_breakdown` DimensionalSlice[], required: Axis/member slices of the same XBRL fact
      - `dimensions` object[], required: List of {axis, member} pairs from the XBRL fact context
      - `value` number, nullable
      - `unit` string, nullable
    - `notes` string[]: Diagnostic notes about missing data, e.g. 'no calculation linkbase'
  - `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

- `404`: No fact for that entity/concept/period.
- `422`: Neither hub_concept_code nor qname was provided.

---

[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)