API reference / Portfolio+

Deduplicated holdings

The same stock held at three brokers comes back as ONE position, with a per-broker contributions breakdown. Filter to equity, mutual funds, ETFs or bonds.

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

Before you integrate

  • When asset_class is set, holdings and holding_count are filtered but totals still cover the whole portfolio.

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.
asset_classstringNoShow only one class: equity, mutual_fund, etf, bond or other.

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/holdings' \
  -H "Authorization: Bearer $GRAPPI_API_KEY"

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "as_of": "2026-11-07T09:30:00.000Z",
    "holding_count": 2,
    "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
          }
        ]
      }
    ],
    "warnings": []
  }
}

Response fields

FieldTypeDescription
as_ofstringWhen the figures were taken, ISO 8601.
holding_countintegerNumber of holdings returned.
totalsobjectHeadline numbers for the whole portfolio, not just the filtered holdings.
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.
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.