API reference / Portfolio+
Portfolio score
A 0-100 structural health score that always ships its own reasons: breadth, concentration, asset mix and standing, each with its weight and a plain-language note.
GET
/v1/portfolio/score- Authentication
- Bearer token
- Scope
portfolio:read
Before you integrate
- With no holdings the score is 0, band poor, with one factor explaining that there is nothing to score yet.
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/score' \ -H "Authorization: Bearer $GRAPPI_API_KEY"
Sample response
{
"request_id": "req_01HZY3K8M2",
"result": {
"as_of": "2026-11-07T09:30:00.000Z",
"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."
}
],
"basis": {
"holding_count": 2,
"source_count": 3,
"effective_holdings": 2,
"top5_weight_percent": 100
},
"disclaimer": "Structural score only. Not investment advice, and no view on any instrument.",
"warnings": []
}
}Response fields
| Field | Type | Description |
|---|---|---|
as_of | string | When the figures were taken, ISO 8601. |
score | number | The score, 0 to 100. |
band | string | poor, fair, good or strong. |
factors | array | The factors that make up the score. |
factors[].id | string | breadth, concentration, asset_mix or standing. |
factors[].label | string | Factor name. |
factors[].score | number | This factor's score, 0 to 100. |
factors[].weight | number | Its share of the final score, 0 to 1. |
factors[].note | string | Plain-words explanation. |
basis | object | The numbers the score was worked out from. |
basis.holding_count | integer | Number of holdings. |
basis.source_count | integer | Number of sources read. |
basis.effective_holdings | number | Effective number of equally sized holdings. |
basis.top5_weight_percent | number | Combined weight of the five largest holdings. |
disclaimer | string | Reminder that the score is structural and not advice. |
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.