---
title: "Get Holding Analytics"
method: POST
path: "/api/portfolio/holding-analytics"
tags: ["Portfolio Analytics"]
---

# Get Holding Analytics

`POST /api/portfolio/holding-analytics`

## Request

- Base URL: `https://api.harmoney.in`
- URL: `https://api.harmoney.in/api/portfolio/holding-analytics`
- Auth: API key in header `x-api-key`

Batch (1-20) hierarchical attribution trees over holdings snapshots, computed in parallel per fund.

## Request body

- HoldingAnalyticsRequest: Request body for POST /api/portfolio/holding-analytics. Two mutually exclusive evaluation-window modes: * **Mode A** — ``as_of`` + ``horizon``: the tree covers ``as_of − horizon`` to ``as_of``. ``horizon`` may be any ``HorizonToken`` (``1M`` / ``3M`` / ``6M`` / ``YTD`` / ``1Y`` / ``3Y`` / ``5Y`` / ``MAX``). * **Mode B** — ``start_date`` + ``end_date``: explicit window. ``rolling_window`` is independent of the outer window — it controls the trailing lookback for ``rolling_return`` / ``rolling_return_contribution`` at every period-end. Required for ``frequency`` in ``{monthly, annual}``; must be omitted when ``frequency="MAX"`` (single-period response has no per-period-end rolling series to compute).
  - `instrument_ids` string[], required: 1-20 fund / portfolio ``unique_id`` values. Each fund is attributed independently — the response carries one ``InstrumentHoldingAnalytics`` entry per requested id.
  - `frequency` 'monthly' | 'annual' | 'MAX', required: The grid the window is measured on. `MAX` measures a single period, weighting every holding at the window's open — ask for `monthly` unless that is what you want.
  - `rolling_window` '3M' | '6M' | '1Y' | '3Y': Trailing lookback for ``rolling_return`` and ``rolling_return_contribution`` at each period-end. Limited to ``3M`` / ``6M`` / ``1Y`` / ``3Y`` — ``YTD`` and ``MAX`` shrink at each period, which breaks the compound arithmetic used for rolling metrics. Required for ``frequency`` in ``{monthly, annual}``; must be omitted when ``frequency="MAX"`` (only one period-end exists, so rolling metrics cannot be computed).
  - `group_by` string[], required: The pivot the tree is built over. `rating` and `tenor` suit debt funds, `sector` / `industry` / `market_cap_category` suit equity funds.
  - `modes` string[]: Optional filter: which PeriodMetrics fields to include on every cell. ``None`` (default) returns all fields — backward-compatible with clients that render multiple attribution views client-side. Pass a subset (e.g. ``["return_contribution", "weight"]``) to shrink the response when only specific views are needed.
  - `portfolio_metrics` string[]: Optional list of portfolio-level valuation metrics to compute from holdings snapshots. Each metric is aggregated as Σ(weight_i × metric_i) / Σ(weight_i) across eligible positions at each period-end, with a ``constituents`` list of the individual instruments that contributed. Currently supported: ``ytm`` (portfolio-weighted yield-to-maturity, debt positions only).
  - `as_of` string, date: Mode A: last period-end for the tree window
  - `horizon` '1M' | '3M' | '6M' | 'YTD' | '1Y' | '3Y' | '5Y' | '10Y' | 'MAX': Mode A: outer-window size — ``as_of − horizon`` becomes the tree window start. Full ``HorizonToken`` set including ``YTD`` and ``MAX``. Independent of ``rolling_window``.
  - `start_date` string, date: Mode B: first period-end for the tree window
  - `end_date` string, date: Mode B: last period-end for the tree window

## Response `200`

Successful Response

- HoldingAnalyticsResponse: Response for POST /api/portfolio/holding-analytics. Batch shape: the echoed request parameters + per-fund attribution results in ``instruments[]`` — one entry per requested ``instrument_id``, in request order. ``requested_start`` / ``requested_end`` echo the resolved outer window (in Mode A they are derived from ``as_of − horizon`` / ``as_of``; in Mode B they are the request values). ``as_of`` and ``horizon`` are echoed only when Mode A was used, so callers can distinguish which mode they sent. ``effective_start`` / ``effective_end`` are the batch-level union (``min(effective_start)``, ``max(effective_end)``) across all funds that returned data — the axis the frontend should render on. Per- fund entries still carry their own ``effective_start`` / ``effective_end`` echoing that fund's own computed span (may be narrower). Each fund's ``periods`` list and tree cells are padded to the batch axis at serialization time with ``no_holdings_data`` null cells for dates outside the fund's own span. ``null`` when no fund resolved.
  - `requested_start` string, date, required
  - `requested_end` string, date, required
  - `effective_start` string, date
  - `effective_end` string, date
  - `as_of` string, date
  - `horizon` '1M' | '3M' | '6M' | 'YTD' | '1Y' | '3Y' | '5Y' | '10Y' | 'MAX'
  - `frequency` 'monthly' | 'annual' | 'MAX', required
  - `rolling_window` '3M' | '6M' | '1Y' | '3Y'
  - `group_by` string[], required
  - `modes` string[]
  - `portfolio_metrics` string[]
  - `instruments` InstrumentHoldingAnalytics[], required
    - `instrument_id` string, required
    - `instrument_name` string
    - `effective_start` string, date, required
    - `effective_end` string, date, required
    - `periods` Period[], required
      - `period_start` string, date, required
      - `period_end` string, date, required
    - `cumulative` Cumulative, required
      - `period_start` string, date, required
      - `period_end` string, date, required
      - `net_return` number
    - `tree` TreeNode, required: One node in the attribution tree. Same shape for every level. ``children`` is omitted on leaf nodes (instrument rows, Expense, Residual). ``isin`` is emitted only on instrument leaves.
      - `name` string, required
      - `isin` string
      - `periods` object, required
      - `children` TreeNode[]
    - `portfolio_metrics` object
    - `null_reason` string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/inferedge/apis/india-mutual-funds-data-feed.md) - [All operations](https://skmtc.dev/inferedge/apis/india-mutual-funds-data-feed/llms.txt) - [OpenAPI document](https://skmtc.dev/inferedge/apis/india-mutual-funds-data-feed/revisions/fe0d3be721c0?raw)