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
| Field | Type | Required | Description |
|---|---|---|---|
connection_ids | string | No | Comma-separated connection ids to include, such as bconn_a,bconn_b. Defaults to every active connection. |
include_cas | string | No | Send 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
| Field | Type | Description |
|---|---|---|
as_of | string | When the figures were taken, ISO 8601. |
totals | object | Headline numbers for the whole portfolio. |
totals.invested_minor | integer | Total cost in paise. |
totals.value_minor | integer | Total market value in paise. |
totals.pnl_minor | integer | Profit or loss in paise. |
totals.pnl_percent | number | Profit or loss as a percent of cost. |
totals.holding_count | integer | Number of distinct holdings. |
totals.source_count | integer | Number of sources read. |
totals.sources_ok | integer | Sources that were read successfully. |
totals.sources_failed | integer | Sources that failed; their holdings are missing from the totals. |
sources | array | Every account or import that was read, including ones that failed. |
sources[].kind | string | broker or cas. |
sources[].id | string | Connection id, or cas_import for the imported statement. |
sources[].provider | string | Broker name, or cas. |
sources[].label | string | The connection's label. |
sources[].status | string | ok or failed. |
sources[].holding_count | integer | Positions this source contributed; 0 when it failed. |
sources[].value_minor | integer | Market value in paise this source contributed. |
sources[].error | object | Present only when the source failed: a code and a message. |
holdings | array | One line per instrument, summed across every source that holds it. |
holdings[].key | string | Stable id of the holding: the ISIN, or a name key when there is no ISIN. |
holdings[].asset_class | string | equity, mutual_fund, etf, bond or other. |
holdings[].isin | string | ISIN, if known. |
holdings[].symbol | string | Trading symbol, if any. |
holdings[].name | string | Instrument name. |
holdings[].quantity | number | Total units held. |
holdings[].avg_cost_minor | integer | Average cost per unit in paise. |
holdings[].ltp_minor | integer | Latest price per unit in paise. |
holdings[].invested_minor | integer | Total cost in paise. |
holdings[].value_minor | integer | Market value in paise. |
holdings[].pnl_minor | integer | Profit or loss in paise. |
holdings[].pnl_percent | number | Profit or loss as a percent of cost. |
holdings[].weight_percent | number | Share of the whole portfolio by value. |
holdings[].source_count | integer | How many sources hold it. |
holdings[].contributions | array | The per-source breakdown. |
holdings[].contributions[].source_id | string | Connection id, or cas_import. |
holdings[].contributions[].provider | string | Broker name, or cas. |
holdings[].contributions[].quantity | number | Units held at that source. |
holdings[].contributions[].avg_cost_minor | integer | Average cost per unit in paise at that source. |
holdings[].contributions[].value_minor | integer | Market value in paise at that source. |
allocation | object | Allocation and concentration. |
allocation.by_asset_class | array | Weights by asset class. |
allocation.by_asset_class[].label | string | Asset class. |
allocation.by_asset_class[].value_minor | integer | Market value in paise. |
allocation.by_asset_class[].weight_percent | number | Share of the portfolio by value. |
allocation.by_asset_class[].holding_count | integer | Holdings in this class. |
allocation.by_source | array | Weights by broker connection or imported statement; same fields as by_asset_class. |
allocation.concentration | object | How concentrated the portfolio is. |
allocation.concentration.top_holding | object | The largest holding, with label, value_minor, weight_percent and holding_count; null when empty. |
allocation.concentration.top5_weight_percent | number | Combined weight of the five largest holdings. |
allocation.concentration.hhi | number | Herfindahl-Hirschman index from 0 to 10000; 10000 is a single holding and about 500 or less is well spread. |
allocation.concentration.effective_holdings | number | 10000 divided by hhi: the number of equally sized holdings that would be as concentrated. |
score | object | A 0 to 100 structural health score with the reasons behind it. |
score.score | number | The score, 0 to 100. |
score.band | string | poor, fair, good or strong. |
score.factors | array | The factors that make up the score. |
score.factors[].id | string | breadth, concentration, asset_mix or standing. |
score.factors[].label | string | Factor name. |
score.factors[].score | number | This factor's score, 0 to 100. |
score.factors[].weight | number | Its share of the final score, 0 to 1. |
score.factors[].note | string | Plain-words explanation. |
warnings | array | Non-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.