---
title: "Portfolio risk model"
method: POST
path: "/v1/portfolio/risk"
---

# Portfolio risk model

`POST /v1/portfolio/risk`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/portfolio/risk`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Return ex-ante portfolio risk: tracking error, CTEV by factor group and by security, ex-ante beta, and the factor-vs-idiosyncratic split, labelled with model coverage.

## Query parameters

- `response_mode` 'compact' | 'standard' | 'verbose'
- `include` string

## Request body

- PortfolioRiskRequest
  - `country` string
  - `lookback` string
  - `category` string
  - `keys` string[]
  - `holdings` PortfolioHoldingInput[], required
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable
  - `benchmark` 'SPY' | 'ACWX' | 'QQQ' | 'IWM' | 'SIXTY_FORTY'
  - `benchmarkLabel` string
  - `benchmarkHoldings` PortfolioHoldingInput[]
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable

## Response `200`

Successful response

- PortfolioRisk
  - `dataAsOf` string
  - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
  - `methodologyVersion` string
  - `materializationVersion` string
  - `object` 'portfolio_risk', required
  - `asOf` string, required
  - `lookback` string, required
  - `benchmarkLabel` string, nullable
  - `trackingError` number, required: Ex-ante total active risk (tracking error), annualised fraction.
  - `totalRisk` number, required: Ex-ante absolute portfolio volatility, annualised fraction.
  - `exAnteBeta` number, required: Ex-ante portfolio beta vs the market factor.
  - `factorRiskShare` number, required: Fraction of active variance from factor exposures (0-1).
  - `specificRiskShare` number, required: Fraction of active variance from idiosyncratic risk (0-1).
  - `factorGroups` PortfolioFactorGroupRisk[], required
    - `object` 'portfolio_factor_group_risk', required
    - `group` string, required
    - `label` string, required
    - `activeExposure` number, required
    - `ctevShare` number, required: Contribution to tracking-error variance (fraction of total TEV).
    - `ctev` number, required: Contribution to tracking error (annualised).
    - `shorterHistory` boolean, required: True for macro factors with a shorter (2022-) covariance history.
  - `factorExposures` PortfolioFactorExposureRisk[], required
    - `object` 'portfolio_factor_exposure_risk', required
    - `factorKey` string, required
    - `factorName` string, required
    - `group` string, required
    - `portfolioBeta` number, required
    - `benchmarkBeta` number, required
    - `activeBeta` number, required
    - `ctevShare` number, required
    - `ctev` number, required
    - `shorterHistory` boolean, required
  - `securities` PortfolioSecurityRisk[], required
    - `object` 'portfolio_security_risk', required
    - `symbol` string, required
    - `weight` number, required
    - `modeled` boolean, required
    - `activeWeight` number, required
    - `specificVol` number, required: Annualised specific (idiosyncratic) volatility for this name.
    - `ctevShare` number, required
    - `ctev` number, required
    - `note` string, nullable
  - `coverage` PortfolioRiskCoverage, required
    - `object` 'portfolio_risk_coverage', required
    - `modeledWeight` number, required: Share of portfolio NAV covered by the factor model (0-1).
    - `modeledHoldings` integer, required
    - `unmodeledHoldings` integer, required
    - `unmodeledSymbols` string[]
    - `totalHoldings` integer, required
    - `covarianceObservations` integer, required: Weekly observations backing the factor covariance estimate.
    - `covarianceEstimable` boolean, required
  - `disclosures` string[], required
  - `summaryMd` string, required
  - `responseMode` 'compact' | 'standard' | 'verbose'
  - `requestId` string
  - `traceparent` string
  - `provenance` ResponseMetadata
    - `source` string, required
    - `sourceLabel` string
    - `sourceAgency` string
    - `canonicality` string
    - `fallbackPolicy` string
    - `accessionNumber` string, nullable, required
    - `filingUrl` string, uri, required
    - `acceptedAt` string, nullable
    - `retrievedAt` string, required
    - `parserVersion` string, required
  - `freshness` FreshnessMetadata: Freshness of the record. For SEC filings, freshness measures the delay between SEC acceptance (`sourcePublishedAt`) and when the record became available in the API — not the age of the document. Statuses: `current` (recently published and available promptly), `archival` (an immutable historical document held in full; its availability delay is not a freshness signal), `degraded`/`stale` (a recently published filing that became available later than the freshness thresholds allow), `fresh` (continuously refreshed datasets recently observed at source), `unknown` (no timestamps). An old immutable filing is never `stale` simply because it was published long ago. `lagMs` is the publish-to-availability delay in milliseconds.
    - `status` 'fresh' | 'current' | 'archival' | 'stale' | 'degraded' | 'unknown', required
    - `asOf` string, required
    - `sourcePublishedAt` string, nullable
    - `lagMs` integer, nullable
  - `materialization` MaterializationMetadata
    - `parserVersion` string, required
    - `materializationVersion` string, required
  - `sourceRights` SourceRightsMetadata
    - `source` string, required
    - `sourceLabel` string
    - `posture` 'public_safe' | 'contract_gated' | 'internal_only' | 'inventory_only' | 'review_required', required
    - `publicAvailability` 'public' | 'contract_gated' | 'internal_only' | 'inventory_only', required
    - `contractStatus` 'approved' | 'review_required' | 'restricted' | 'prohibited' | 'expired', required
    - `restrictions` string[]
    - `notes` string, nullable
  - `methodology` MethodologyMetadata
    - `id` string, required
    - `version` string, required
    - `summary` string, required
    - `confidence` 'high' | 'medium' | 'low', required
    - `launchState` 'experimental' | 'beta' | 'ga', required
    - `inputs` string[]
    - `validation` object
  - `revision` RevisionMetadata
    - `sourcePublishedAt` string, nullable
    - `retrievedAt` string, required
    - `vintageId` string, nullable
    - `revisedFrom` string, nullable
  - `degradedState` DegradedState
    - `code` string, required
    - `message` string, required
    - `retryable` boolean, required
    - `missingCapabilities` string[]
    - `fallbackUsed` string[]

## Other responses

- `default`: Contract-aware error response

---

[API](https://skmtc.dev/turos/apis/turos-api.md) · [All operations](https://skmtc.dev/turos/apis/turos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/turos/apis/turos-api/revisions/a68d3ec80a56?raw)