---
title: "Portfolio intelligence bundle"
method: POST
path: "/v1/intelligence/portfolio"
---

# Portfolio intelligence bundle

`POST /v1/intelligence/portfolio`

## Request

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

Return a one-call portfolio intelligence bundle with exposures, stress scenarios, events, and hedge ideas.

## Request body

- PortfolioIntelligenceRequest
  - `country` string
  - `lookback` string
  - `category` string
  - `keys` string[]
  - `benchmarkLabel` string
  - `benchmarkHoldings` PortfolioHoldingInput[]
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable
  - `whatIfLabel` string
  - `whatIfHoldings` PortfolioHoldingInput[]
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable
  - `holdings` PortfolioHoldingInput[], required
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable

## Response `200`

Successful response

- PortfolioAnalysis
  - `dataAsOf` string
  - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
  - `methodologyVersion` string
  - `materializationVersion` string
  - `object` 'portfolio_analysis', required
  - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
  - `id` string, required
  - `asOf` string, date-time, required
  - `country` string
  - `lookback` string
  - `category` string
  - `holdings` PortfolioHoldingInput[], required
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable
  - `exposures` FactorExposure[], required
    - `dataAsOf` string
    - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
    - `methodologyVersion` string
    - `materializationVersion` string
    - `object` 'factor_exposure', required
    - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
    - `id` string, required
    - `subjectType` 'security' | 'portfolio' | 'watchlist', required
    - `subjectKey` string, required
    - `factorKey` string, required
    - `factorName` string
    - `factorCategory` string
    - `beta` number, required
    - `intercept` number, nullable
    - `rSquared` number, nullable
    - `adjustedRSquared` number, nullable
    - `tStat` number, nullable
    - `observationCount` integer, nullable
    - `nActiveFactors` integer, nullable
    - `percentile` number, nullable
    - `confidence` 'high' | 'medium' | 'low', nullable
    - `modelName` string, nullable
    - `asOf` string, date-time, required
    - `expansionHints` string[]
    - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs. Omitted on low-risk compact responses.
    - `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[]
  - `fit` PortfolioFitSummary, required
    - `object` 'portfolio_fit_summary', required
    - `exposureCount` integer, required
    - `activeFactorCount` integer, required
    - `averageRSquared` number, nullable, required: Unweighted average of the underlying factor-exposure diagnostic R-squared values. This is an exposure-model fit proxy, not a realized portfolio return attribution R-squared.
    - `averageAdjustedRSquared` number, nullable, required
    - `idiosyncraticRiskScore` number, nullable, required: One-minus-average-R-squared exposure diagnostic proxy. Use it to compare residual factor explainability across portfolios, not as a realized residual-return volatility estimate.
    - `rSquaredMethod` 'unweighted_average_of_factor_exposure_r_squared', required: Method used for averageRSquared.
    - `idiosyncraticRiskMethod` 'one_minus_average_factor_exposure_r_squared_proxy', required: Method used for idiosyncraticRiskScore.
    - `observationCount` integer, nullable, required
    - `interpretation` string, required
  - `benchmarkLabel` string, nullable, required
  - `benchmarkTilts` PortfolioBenchmarkTilt[], required
    - `object` 'portfolio_benchmark_tilt', required
    - `factorKey` string, required
    - `portfolioBeta` number, required
    - `benchmarkBeta` number, required
    - `activeTilt` number, required
    - `direction` 'overweight' | 'underweight' | 'neutral', required
    - `summary` string, required
  - `whatIfComparison` PortfolioWhatIfComparison, required
    - `object` 'portfolio_what_if_comparison', required
    - `label` string, required
    - `holdings` PortfolioHoldingInput[], required
      - `symbol` string, required
      - `weight` number, required
      - `shares` number, nullable
      - `costBasis` number, nullable
    - `exposureDeltas` PortfolioBenchmarkTilt[], required
      - `object` 'portfolio_benchmark_tilt', required
      - `factorKey` string, required
      - `portfolioBeta` number, required
      - `benchmarkBeta` number, required
      - `activeTilt` number, required
      - `direction` 'overweight' | 'underweight' | 'neutral', required
      - `summary` string, required
    - `summaryMd` string, required
  - `positionViews` PortfolioPositionFactorView[], required
    - `object` 'portfolio_position_factor_view', required
    - `symbol` string, required
    - `holding` PortfolioHoldingInput, required
      - `symbol` string, required
      - `weight` number, required
      - `shares` number, nullable
      - `costBasis` number, nullable
    - `activeFactorCount` integer, required
    - `topFactors` FactorExposure[], required
      - `dataAsOf` string
      - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
      - `methodologyVersion` string
      - `materializationVersion` string
      - `object` 'factor_exposure', required
      - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
      - `id` string, required
      - `subjectType` 'security' | 'portfolio' | 'watchlist', required
      - `subjectKey` string, required
      - `factorKey` string, required
      - `factorName` string
      - `factorCategory` string
      - `beta` number, required
      - `intercept` number, nullable
      - `rSquared` number, nullable
      - `adjustedRSquared` number, nullable
      - `tStat` number, nullable
      - `observationCount` integer, nullable
      - `nActiveFactors` integer, nullable
      - `percentile` number, nullable
      - `confidence` 'high' | 'medium' | 'low', nullable
      - `modelName` string, nullable
      - `asOf` string, date-time, required
      - `expansionHints` string[]
      - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs. Omitted on low-risk compact responses.
      - `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[]
    - `summaryMd` string, required
    - `drillTargets` object, required
      - `loadings` object, required
        - `label` string, required
        - `method` 'GET', required
        - `path` string, required
      - `decomposition` object, required
        - `label` string, required
        - `method` 'GET', required
        - `path` string, required
  - `positionExposures` FactorExposure[], required
    - `dataAsOf` string
    - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
    - `methodologyVersion` string
    - `materializationVersion` string
    - `object` 'factor_exposure', required
    - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
    - `id` string, required
    - `subjectType` 'security' | 'portfolio' | 'watchlist', required
    - `subjectKey` string, required
    - `factorKey` string, required
    - `factorName` string
    - `factorCategory` string
    - `beta` number, required
    - `intercept` number, nullable
    - `rSquared` number, nullable
    - `adjustedRSquared` number, nullable
    - `tStat` number, nullable
    - `observationCount` integer, nullable
    - `nActiveFactors` integer, nullable
    - `percentile` number, nullable
    - `confidence` 'high' | 'medium' | 'low', nullable
    - `modelName` string, nullable
    - `asOf` string, date-time, required
    - `expansionHints` string[]
    - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs. Omitted on low-risk compact responses.
    - `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[]
  - `attribution` object[], required
  - `hedgeSuggestions` object[], required
  - `optimizationNotes` string[], required
  - `factorNeutralPlan` string[], required
  - `optimizerObjective` 'factor_neutral' | 'min_drawdown' | 'regime_aware'
  - `optimizerConstraints` PortfolioOptimizerConstraints
    - `maxCandidates` integer
    - `maxIterations` integer
    - `maxRuntimeMs` integer
    - `maxPositionWeight` number
    - `minPositionWeight` number
    - `longOnly` boolean
    - `turnoverLimit` number
    - `riskFreeRate` number
  - `optimizerRuntime` PortfolioOptimizerRuntime
    - `object` 'portfolio_optimizer_runtime', required
    - `method` 'bounded_deterministic_candidate_search', required
    - `candidateCount` integer, required
    - `iterationBudget` integer, required
    - `iterationsRun` integer, required
    - `runtimeMs` number, required
    - `maxRuntimeMs` integer, required
    - `timeout` boolean, required
  - `optimizerCandidates` PortfolioOptimizerCandidate[]
    - `object` 'portfolio_optimizer_candidate', required
    - `rank` integer, required
    - `name` string, required
    - `objective` 'current_reference' | 'factor_neutral' | 'min_drawdown' | 'regime_aware', required
    - `holdings` PortfolioHoldingInput[], required
      - `symbol` string, required
      - `weight` number, required
      - `shares` number, nullable
      - `costBasis` number, nullable
    - `expectedReturn` number, required
    - `expectedVolatility` number, required
    - `expectedSharpe` number, required
    - `maxDrawdownProxy` number, required
    - `factorExposureScore` number, required
    - `turnover` number, required
    - `score` number, required
    - `constraintStatus` 'ok' | 'capped' | 'rejected', required
    - `constraintsApplied` string[], required
    - `rationale` string, required
  - `optimizerCandidateCount` integer
  - `optimizerCandidateSample` PortfolioOptimizerCandidateSummary[]
    - `object` 'portfolio_optimizer_candidate', required
    - `rank` integer, required
    - `name` string, required
    - `objective` 'current_reference' | 'factor_neutral' | 'min_drawdown' | 'regime_aware', required
    - `expectedReturn` number, required
    - `expectedVolatility` number, required
    - `expectedSharpe` number, required
    - `maxDrawdownProxy` number, required
    - `factorExposureScore` number, required
    - `turnover` number, required
    - `score` number, required
    - `constraintStatus` 'ok' | 'capped' | 'rejected', required
    - `constraintsApplied` string[], required
    - `rationale` string, required
  - `selectedCandidate` union
    - PortfolioOptimizerCandidate
      - `object` 'portfolio_optimizer_candidate', required
      - `rank` integer, required
      - `name` string, required
      - `objective` 'current_reference' | 'factor_neutral' | 'min_drawdown' | 'regime_aware', required
      - `holdings` PortfolioHoldingInput[], required
        - `symbol` string, required
        - `weight` number, required
        - `shares` number, nullable
        - `costBasis` number, nullable
      - `expectedReturn` number, required
      - `expectedVolatility` number, required
      - `expectedSharpe` number, required
      - `maxDrawdownProxy` number, required
      - `factorExposureScore` number, required
      - `turnover` number, required
      - `score` number, required
      - `constraintStatus` 'ok' | 'capped' | 'rejected', required
      - `constraintsApplied` string[], required
      - `rationale` string, required
    - PortfolioOptimizerCandidateSummary
      - `object` 'portfolio_optimizer_candidate', required
      - `rank` integer, required
      - `name` string, required
      - `objective` 'current_reference' | 'factor_neutral' | 'min_drawdown' | 'regime_aware', required
      - `expectedReturn` number, required
      - `expectedVolatility` number, required
      - `expectedSharpe` number, required
      - `maxDrawdownProxy` number, required
      - `factorExposureScore` number, required
      - `turnover` number, required
      - `score` number, required
      - `constraintStatus` 'ok' | 'capped' | 'rejected', required
      - `constraintsApplied` string[], required
      - `rationale` string, required
  - `optimizerDisclosures` string[]
  - `summaryMd` string, required
  - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs. Omitted on low-risk compact responses.
  - `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[]
  - `requestId` string
  - `traceparent` 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)