API reference / Portfolio+

Consolidated portfolio

Every linked broker plus the imported CAS in one view: holdings deduplicated by ISIN, totals, P&L, allocation, concentration and score. One call, whatever the brokers.

GET/v1/portfolio
Authentication
Bearer token
Scope
portfolio:read

Before you integrate

  • Reads every active broker connection, plus your imported statement unless include_cas is false. A broker that fails (for example an expired token) is listed in sources with status failed and its holdings are left out of the totals.
  • The same stock held at several brokers appears once in holdings, with the split in contributions.

Query parameters

FieldTypeRequiredDescription
connection_idsstringNoComma-separated connection ids to include, such as bconn_a,bconn_b. Defaults to every active connection.
include_casstringNoSend false to leave the imported statement out and use broker accounts only. Defaults to true.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X GET 'https://grappi.ai/v1/portfolio' \
  -H "Authorization: Bearer $GRAPPI_API_KEY"

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "as_of": "2026-11-07T09:30:00.000Z",
    "totals": {
      "invested_minor": 7750250,
      "value_minor": 8837035,
      "pnl_minor": 1086785,
      "pnl_percent": 14.02,
      "holding_count": 2,
      "source_count": 3,
      "sources_ok": 3,
      "sources_failed": 0
    },
    "sources": [
      {
        "kind": "broker",
        "id": "bconn_a1b2c3d4e5f60718",
        "provider": "zerodha",
        "label": "zerodha (live)",
        "status": "ok",
        "holding_count": 1,
        "value_minor": 2950000
      },
      {
        "kind": "broker",
        "id": "bconn_b2c3d4e5f6071829",
        "provider": "upstox",
        "label": "upstox (live)",
        "status": "ok",
        "holding_count": 1,
        "value_minor": 1475000
      },
      {
        "kind": "cas",
        "id": "cas_import",
        "provider": "cas",
        "label": "Imported statement",
        "status": "ok",
        "holding_count": 1,
        "value_minor": 4412035
      }
    ],
    "holdings": [
      {
        "key": "INE123A01012",
        "asset_class": "equity",
        "isin": "INE123A01012",
        "symbol": "RELIANCE",
        "name": "RELIANCE",
        "quantity": 15,
        "avg_cost_minor": 250000,
        "ltp_minor": 295000,
        "invested_minor": 3750000,
        "value_minor": 4425000,
        "pnl_minor": 675000,
        "pnl_percent": 18,
        "weight_percent": 50.07,
        "source_count": 2,
        "contributions": [
          {
            "source_id": "bconn_a1b2c3d4e5f60718",
            "provider": "zerodha",
            "quantity": 10,
            "avg_cost_minor": 250000,
            "value_minor": 2950000
          },
          {
            "source_id": "bconn_b2c3d4e5f6071829",
            "provider": "upstox",
            "quantity": 5,
            "avg_cost_minor": 250000,
            "value_minor": 1475000
          }
        ]
      },
      {
        "key": "INF123K01014",
        "asset_class": "mutual_fund",
        "isin": "INF123K01014",
        "symbol": null,
        "name": "Sample Liquid Fund - Growth",
        "quantity": 124.239,
        "avg_cost_minor": 32198,
        "ltp_minor": 35512,
        "invested_minor": 4000250,
        "value_minor": 4412035,
        "pnl_minor": 411785,
        "pnl_percent": 10.29,
        "weight_percent": 49.93,
        "source_count": 1,
        "contributions": [
          {
            "source_id": "cas_import",
            "provider": "cas",
            "quantity": 124.239,
            "avg_cost_minor": 32198,
            "value_minor": 4412035
          }
        ]
      }
    ],
    "allocation": {
      "by_asset_class": [
        {
          "label": "equity",
          "value_minor": 4425000,
          "weight_percent": 50.07,
          "holding_count": 1
        },
        {
          "label": "mutual_fund",
          "value_minor": 4412035,
          "weight_percent": 49.93,
          "holding_count": 1
        }
      ],
      "by_source": [
        {
          "label": "zerodha (live)",
          "value_minor": 2950000,
          "weight_percent": 33.38,
          "holding_count": 1
        },
        {
          "label": "upstox (live)",
          "value_minor": 1475000,
          "weight_percent": 16.69,
          "holding_count": 1
        },
        {
          "label": "Imported statement",
          "value_minor": 4412035,
          "weight_percent": 49.93,
          "holding_count": 1
        }
      ],
      "concentration": {
        "top_holding": {
          "label": "RELIANCE",
          "value_minor": 4425000,
          "weight_percent": 50.07,
          "holding_count": 1
        },
        "top5_weight_percent": 100,
        "hhi": 5000,
        "effective_holdings": 2
      }
    },
    "score": {
      "score": 41.69,
      "band": "fair",
      "factors": [
        {
          "id": "breadth",
          "label": "Breadth",
          "score": 10,
          "weight": 0.3,
          "note": "2 holding(s), 2 of them effective after weighting. 20 effective holdings scores full."
        },
        {
          "id": "concentration",
          "label": "Concentration",
          "score": 0,
          "weight": 0.3,
          "note": "Top 5 holdings are 100% of value; the largest alone is 50.07%. Lower is better. 40% top-5 and 10% single scores full."
        },
        {
          "id": "asset_mix",
          "label": "Asset mix",
          "score": 100,
          "weight": 0.2,
          "note": "2 asset class(es): equity 50.07%, mutual_fund 49.93%."
        },
        {
          "id": "standing",
          "label": "Standing vs cost",
          "score": 93.47,
          "weight": 0.2,
          "note": "Unrealized P&L is 14.02% on cost. A gain of 15% or better scores full. Structure only, not advice."
        }
      ]
    },
    "warnings": []
  }
}

Response fields

FieldTypeDescription
as_ofstringWhen the figures were taken, ISO 8601.
totalsobjectHeadline numbers for the whole portfolio.
totals.invested_minorintegerTotal cost in paise.
totals.value_minorintegerTotal market value in paise.
totals.pnl_minorintegerProfit or loss in paise.
totals.pnl_percentnumberProfit or loss as a percent of cost.
totals.holding_countintegerNumber of distinct holdings.
totals.source_countintegerNumber of sources read.
totals.sources_okintegerSources that were read successfully.
totals.sources_failedintegerSources that failed; their holdings are missing from the totals.
sourcesarrayEvery account or import that was read, including ones that failed.
sources[].kindstringbroker or cas.
sources[].idstringConnection id, or cas_import for the imported statement.
sources[].providerstringBroker name, or cas.
sources[].labelstringThe connection's label.
sources[].statusstringok or failed.
sources[].holding_countintegerPositions this source contributed; 0 when it failed.
sources[].value_minorintegerMarket value in paise this source contributed.
sources[].errorobjectPresent only when the source failed: a code and a message.
holdingsarrayOne line per instrument, summed across every source that holds it.
holdings[].keystringStable id of the holding: the ISIN, or a name key when there is no ISIN.
holdings[].asset_classstringequity, mutual_fund, etf, bond or other.
holdings[].isinstringISIN, if known.
holdings[].symbolstringTrading symbol, if any.
holdings[].namestringInstrument name.
holdings[].quantitynumberTotal units held.
holdings[].avg_cost_minorintegerAverage cost per unit in paise.
holdings[].ltp_minorintegerLatest price per unit in paise.
holdings[].invested_minorintegerTotal cost in paise.
holdings[].value_minorintegerMarket value in paise.
holdings[].pnl_minorintegerProfit or loss in paise.
holdings[].pnl_percentnumberProfit or loss as a percent of cost.
holdings[].weight_percentnumberShare of the whole portfolio by value.
holdings[].source_countintegerHow many sources hold it.
holdings[].contributionsarrayThe per-source breakdown.
holdings[].contributions[].source_idstringConnection id, or cas_import.
holdings[].contributions[].providerstringBroker name, or cas.
holdings[].contributions[].quantitynumberUnits held at that source.
holdings[].contributions[].avg_cost_minorintegerAverage cost per unit in paise at that source.
holdings[].contributions[].value_minorintegerMarket value in paise at that source.
allocationobjectAllocation and concentration.
allocation.by_asset_classarrayWeights by asset class.
allocation.by_asset_class[].labelstringAsset class.
allocation.by_asset_class[].value_minorintegerMarket value in paise.
allocation.by_asset_class[].weight_percentnumberShare of the portfolio by value.
allocation.by_asset_class[].holding_countintegerHoldings in this class.
allocation.by_sourcearrayWeights by broker connection or imported statement; same fields as by_asset_class.
allocation.concentrationobjectHow concentrated the portfolio is.
allocation.concentration.top_holdingobjectThe largest holding, with label, value_minor, weight_percent and holding_count; null when empty.
allocation.concentration.top5_weight_percentnumberCombined weight of the five largest holdings.
allocation.concentration.hhinumberHerfindahl-Hirschman index from 0 to 10000; 10000 is a single holding and about 500 or less is well spread.
allocation.concentration.effective_holdingsnumber10000 divided by hhi: the number of equally sized holdings that would be as concentrated.
scoreobjectA 0 to 100 structural health score with the reasons behind it.
score.scorenumberThe score, 0 to 100.
score.bandstringpoor, fair, good or strong.
score.factorsarrayThe factors that make up the score.
score.factors[].idstringbreadth, concentration, asset_mix or standing.
score.factors[].labelstringFactor name.
score.factors[].scorenumberThis factor's score, 0 to 100.
score.factors[].weightnumberIts share of the final score, 0 to 1.
score.factors[].notestringPlain-words explanation.
warningsarrayNon-fatal problems, such as a broker that could not be read.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.