/api/v1/portfolio/portfolios/{portfolio_id}/allocationRead portfolio allocation
Returns exact allocation values and decimal weights from the portfolio valuation. SECURITY groups existing instrument marks and cash; CURRENCY groups the supported reporting currency; ACCOUNT retains existing account allocation. Values sum to the portfolio total and nonempty weights sum to one.
freeSince v3.156.0
Why use this
Display a breakdown of current portfolio value.
Common use case
Show security, currency or account allocation beside saved holdings.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| portfolio_id | path | required | — | — | Portfolio identifier owned by the authenticated user. | 00000000-0000-4000-8000-000000000004 |
| dimension | query | required | — | ASSET_CLASS, SECTOR, INDUSTRY, COUNTRY, CURRENCY, ACCOUNT, SECURITY | Grouping dimension. Positioned USD portfolios currently support ACCOUNT, SECURITY and CURRENCY. Unsupported positioned dimensions return SERVICE_UNAVAILABLE; they are not invented from missing classifications. | SECURITY |
| currency | query | optional | — | — | Reporting currency; must match the supported portfolio base currency. | USD |
| as_of | query | optional | — | — | Optional exact source timestamp in UTC. A snapshot without matching authority remains unavailable. | 2026-09-13T00:00:00.000000Z |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| status | string | no | success. |
| request_id | string | no | Request correlation identifier. |
| timestamp | string | no | Response time in UTC. |
| data | object | no | Adopted portfolio allocation result. |
| meta | object | no | Source timestamp, freshness, coverage counts, version and explicit omissions. |
Sample response
·
- "status": "success"
- "request_id": "portfolio-documentation-example"
- "timestamp": "2026-09-13T00:00:00.000000Z"
- "data":
- "portfolio_id": "00000000-0000-4000-8000-000000000004"
- "as_of": "2026-09-13T00:00:00.000000Z"
- "dimension": "CURRENCY"
- "currency": "USD"
- "total_value": "125.5"
- "buckets":
- "meta":
- "source_as_of": "2026-09-13T00:00:00.000000Z"
- "freshness": "FRESH"
- "coverage":
- "version": "source-v1"
- "omissions": []
Errors
| Status | Label | Description |
|---|---|---|
| 200 | Successful response with source freshness metadata. | |
| 400 | INVALID_REQUEST: invalid or unsupported query shape. | |
| 401 | UNAUTHENTICATED: a valid Portfolio Day Pass is required. | |
| 403 | FORBIDDEN: scope or entitlement does not permit the operation. | |
| 404 | NOT_FOUND: portfolio is absent or not owned by the caller. | |
| 429 | RATE_LIMITED: retry after the supplied delay. | |
| 503 | SERVICE_UNAVAILABLE or typed source validation failure: the requested authoritative result is not ready. |
Code samples
curl "https://api.finradar.ai/api/v1/portfolio/portfolios/00000000-0000-4000-8000-000000000004/allocation?dimension=SECURITY¤cy=USD&as_of=2026-09-13T00%3A00%3A00.000000Z" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).