Portfolio Tracker Overview

The Portfolio Tracker turns a one-shot portfolio analysis into a persistent object that Parallax keeps current for you. Unlike /v1/portfolio/analyze — which recomputes a portfolio’s entire history on every call — a tracked portfolio is stored once and then advanced day-by-day by appending only new days. This reduces repeated computation for daily dashboards and ongoing monitoring.

Each tracked portfolio keeps a boundary marking the last persisted per-RIC value and benchmark level. Incremental updates extend the analytics from that boundary, carrying forward portfolio and benchmark values across updates.

Lifecycle

Validate & resolve (optional)

Use Validate Portfolio to check a portfolio definition (per-date weights must sum to 1.0, symbols must resolve) and Resolve Portfolio to normalize symbols to RICs before you commit to tracking.

Track

Track Portfolio registers the portfolio and kicks off its initial analytics in the background, returning a portfolio_key immediately (no compute wait). The portfolio is initializing until its analytics persist.

Read analytics

Poll Get Analytics. It returns a discriminated status: not_computed (200) while the background compute hasn’t landed yet, then ready with the full analytics series. Reads use stored series. If the cached analytics are missing or use an older calculation version, the read derives updated analytics from those series.

Keep it current

Increment brings a portfolio forward to yesterday by appending only the missing trading days. Active portfolios are advanced automatically by a daily worker, so this is usually hands-off.

Amend or remove

Update changes the definition (holdings, benchmark, currency, initial value) and recomputes; Delete removes the portfolio and all its data.

Endpoints

Endpoint	Method	Purpose
Track	`POST /v1/portfolio/track`	Register a portfolio and start initial analytics
Validate	`POST /v1/portfolio/validate`	Validate a portfolio definition before tracking
Resolve	`POST /v1/portfolio/resolve`	Resolve/normalize symbols to RICs
Get Portfolio	`GET /v1/portfolio/{portfolio_key}`	Portfolio metadata
Get Summary	`GET /v1/portfolio/{portfolio_key}/summary`	Headline summary
Get Analytics	`GET /v1/portfolio/{portfolio_key}/analytics`	Derived analytics series (`ready`/`not_computed`)
Get Holdings	`GET /v1/portfolio/{portfolio_key}/holdings`	Holdings over time
Latest Holdings	`GET /v1/portfolio/{portfolio_key}/holdings/latest`	Most recent holdings
Increment	`POST /v1/portfolio/{portfolio_key}/increment`	Append new trading days
Update	`POST /v1/portfolio/{portfolio_key}/update`	Replace/amend the definition and recompute
Validate Update	`POST /v1/portfolio/{portfolio_key}/validate`	Validate an update before applying
Delete	`DELETE /v1/portfolio/{portfolio_key}`	Delete the portfolio and its data

Typical flow

# 1. Register a tracked portfolio -> returns a portfolio_key immediately
curl -s https://api.chicago.global/v1/portfolio/track \
  -H "Authorization: Bearer $PARALLAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio": [
      { "date": "2024-01-01", "symbol": "AAPL.O", "weight": 0.5 },
      { "date": "2024-01-01", "symbol": "MSFT.O", "weight": 0.5 }
    ],
    "base_currency": "USD",
    "benchmark": "ACWI.OQ",
    "initial_value": 10000
  }'
# => { "success": true, "portfolio_key": "pf_...", "analytics_job_id": "...", "portfolio": { ... } }

# 2. Poll analytics until status == "ready"
curl -s https://api.chicago.global/v1/portfolio/pf_.../analytics \
  -H "Authorization: Bearer $PARALLAX_API_KEY"
# => { "status": "not_computed" }  ... then { "status": "ready", "analytics": { ... } }

# 3. (Automatic daily, or on demand) bring analytics forward to yesterday
curl -s -X POST https://api.chicago.global/v1/portfolio/pf_.../increment \
  -H "Authorization: Bearer $PARALLAX_API_KEY"

Where a tracker operation accepts end_date, a future date is capped at yesterday. Rebalance weights must sum to 1.0 for each date. The initial track request does not accept an end_date; see the request schema for each operation.

Last modified on October 19, 2026

Overview

Portfolio Analysis