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

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/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

FieldTypeDescription
as_ofstringWhen the figures were taken, ISO 8601.
scorenumberThe score, 0 to 100.
bandstringpoor, fair, good or strong.
factorsarrayThe factors that make up the score.
factors[].idstringbreadth, concentration, asset_mix or standing.
factors[].labelstringFactor name.
factors[].scorenumberThis factor's score, 0 to 100.
factors[].weightnumberIts share of the final score, 0 to 1.
factors[].notestringPlain-words explanation.
basisobjectThe numbers the score was worked out from.
basis.holding_countintegerNumber of holdings.
basis.source_countintegerNumber of sources read.
basis.effective_holdingsnumberEffective number of equally sized holdings.
basis.top5_weight_percentnumberCombined weight of the five largest holdings.
disclaimerstringReminder that the score is structural and not advice.
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.