---
title: "Model factor analysis"
method: POST
path: "/v1/models/factor-analysis"
---

# Model factor analysis

`POST /v1/models/factor-analysis`

## Request

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

Return model factor analysis for submitted Model Builder or saved-model holdings with optional attribution, hedge, and optimizer sections.

## Query parameters

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

## Request body

- ModelFactorAnalysisRequest
  - `model` ModelFactorAnalysisModelInput
    - `id` string
    - `label` string
    - `description` string
    - `tags` string[]
    - `source` 'turos' | 'client' | 'model_builder'
  - `country` string
  - `lookback` string
  - `window` string
  - `category` string
  - `keys` string[]
  - `include` ModelFactorAnalysisInclude
    - `attribution` boolean
    - `hedge` boolean
    - `optimizer` boolean
    - `positionViews` boolean
  - `hedge` ModelFactorAnalysisHedgeOptions
    - `objective` 'factor_neutral' | 'min_drawdown' | 'regime_aware'
    - `mode` 'compact' | 'standard'
    - `constraints` PortfolioHedgeConstraints
      - `maxHedges` integer
      - `maxPositionWeight` number
      - `maxTotalHedgeWeight` number
      - `maxSectorWeight` number
      - `hedgeIntensity` number
      - `longOnly` boolean
      - `allowedInstrumentTypes` PortfolioHedgeInstrumentType[]
      - `customUniverse` string[]
      - `targetExposures` object
      - `minConfidence` 'low' | 'medium' | 'high'
      - `minLiquidityUsd` number
      - `excludedSectors` string[]
  - `optimizer` ModelFactorAnalysisOptimizerOptions
    - `objective` 'factor_neutral' | 'min_drawdown' | 'regime_aware'
    - `constraints` PortfolioOptimizerConstraints
      - `maxCandidates` integer
      - `maxIterations` integer
      - `maxRuntimeMs` integer
      - `maxPositionWeight` number
      - `minPositionWeight` number
      - `longOnly` boolean
      - `turnoverLimit` number
      - `riskFreeRate` number
  - `holdings` PortfolioHoldingInput[], required
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable

## Response `200`

Successful response

- ModelFactorAnalysis
  - `dataAsOf` string
  - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
  - `methodologyVersion` string
  - `materializationVersion` string
  - `object` 'model_factor_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
  - `model` object, required
    - `id` string, required
    - `label` string, required
    - `description` string, required
    - `tags` string[], required
    - `source` 'turos' | 'client' | 'model_builder', required
  - `country` string, required
  - `lookback` string, required
  - `window` string, required
  - `category` string, required
  - `holdings` PortfolioHoldingInput[], required
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable
  - `include` ModelFactorAnalysisInclude, required
    - `attribution` boolean
    - `hedge` boolean
    - `optimizer` boolean
    - `positionViews` boolean
  - `analysis` PortfolioAnalysis, required
    - `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
  - `attribution` PortfolioAttribution, required
    - `dataAsOf` string
    - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
    - `methodologyVersion` string
    - `materializationVersion` string
    - `object` 'portfolio_attribution', 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
    - `analysisId` string, required
    - `asOf` string, date-time, required
    - `country` string, required
    - `window` string, required
    - `lookback` string, required
    - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annual', required
    - `holdings` PortfolioHoldingInput[], required
      - `symbol` string, required
      - `weight` number, required
      - `shares` number, nullable
      - `costBasis` number, nullable
    - `portfolioReturn` number, nullable, required
    - `totalExplained` number, required
    - `alpha` number, nullable, required
    - `rSquared` number, nullable, required
    - `contributions` PortfolioFactorAttribution[], required
      - `object` 'portfolio_factor_attribution', required
      - `rank` integer, required
      - `factorKey` string, required
      - `factorName` string, required
      - `factorCategory` string, required
      - `contributionPercent` number, required
      - `contributionPct` number, nullable, required
      - `beta` number, required
      - `factorReturn` number, required
      - `rawReturn` number, nullable
      - `pureReturn` number, nullable
      - `scaledReturn` number, nullable
      - `zScore` number, nullable
      - `leverage` number, nullable
      - `modelName` string, nullable
      - `explanation` string, required
      - `trace` Trace
        - `object` 'trace', required
        - `id` string, required
        - `createdAt` string, required
        - `livemode` boolean, required
        - `kind` 'filing_fact' | 'filing_excerpt' | 'derived_metric' | 'source_record', required
        - `status` 'supported' | 'degraded' | 'unavailable', required
        - `title` string, required
        - `summary` string, nullable
        - `formula` string, nullable
        - `filing` object, nullable
          - `accessionNumber` string, required
          - `filingUrl` string, uri, required
          - `pdfUrl` string, uri, nullable
          - `viewerUrl` string, uri, nullable
          - `filingDate` string, nullable
          - `reportDate` string, nullable
          - `form` string, nullable
          - `page` integer, nullable
          - `region` object, nullable
            - `status` 'supported' | 'degraded' | 'unavailable', required
            - `kind` 'inline_xbrl_fact' | 'html_text_range', nullable
            - `startOffset` integer, nullable
            - `endOffset` integer, nullable
            - `snippet` string, nullable
            - `viewerFragment` string, nullable
        - `sourceRecord` object, nullable
          - `sourceName` string, required
          - `sourceKind` string, required
          - `sourceKey` string, required
          - `sourceUrl` string, uri, required
          - `publicationTs` string, nullable
          - `firstObservedAt` string, nullable
          - `lastObservedAt` string, nullable
          - `latestIngestedAt` string, nullable
          - `latestHttpStatus` integer, nullable
          - `latestStorageRef` string, nullable
          - `lineage` object
          - `metadata` object
          - `error` string, nullable
        - `nodes` object[], required
          - `id` string, required
          - `kind` 'xbrl_fact' | 'filing_document' | 'filing_excerpt' | 'derived_formula' | 'source_document' | 'source_record', required
          - `source` 'disclosed' | 'derived' | 'observed', required
          - `label` string, required
          - `value` union
            - string
            - number
          - `unit` string, nullable
          - `taxonomy` string, nullable
          - `tag` string, nullable
          - `filingUrl` string, uri, nullable
          - `documentUrl` string, uri, nullable
          - `pdfUrl` string, uri, nullable
          - `viewerUrl` string, uri, nullable
          - `accessionNumber` string, nullable
          - `sourceName` string, nullable
          - `sourceKind` string, nullable
          - `sourceKey` string, nullable
          - `sourceSurface` string, nullable
          - `publishedAt` string, nullable
          - `page` integer, nullable
          - `region` object, nullable
            - `status` 'supported' | 'degraded' | 'unavailable', required
            - `kind` 'inline_xbrl_fact' | 'html_text_range', nullable
            - `startOffset` integer, nullable
            - `endOffset` integer, nullable
            - `snippet` string, nullable
            - `viewerFragment` string, nullable
          - `periodStart` string, nullable
          - `periodEnd` string, nullable
          - `segmentAxis` string, nullable
          - `segmentMember` string, nullable
          - `segmentLabel` string, nullable
    - `returnStream` PortfolioReturnPoint[]
      - `object` 'portfolio_return_point', required
      - `period` string, required
      - `periodEnd` string, date, required
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annual', required
      - `periodReturn` number, required
      - `cumulativeReturn` number, required
      - `coverageWeight` number, required
      - `missingSymbols` string[], required
    - `returnPointCount` integer
    - `returnStreamSample` PortfolioReturnPoint[]
      - `object` 'portfolio_return_point', required
      - `period` string, required
      - `periodEnd` string, date, required
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annual', required
      - `periodReturn` number, required
      - `cumulativeReturn` number, required
      - `coverageWeight` number, required
      - `missingSymbols` string[], required
    - `rollingBetas` PortfolioRollingBeta[]
      - `object` 'portfolio_rolling_beta', required
      - `factorKey` string, required
      - `factorName` string, required
      - `factorCategory` string, required
      - `beta` number, required
      - `lookback` string, required
      - `windowStart` string, date, nullable, required
      - `windowEnd` string, date, required
      - `rSquared` number, nullable, required
      - `adjustedRSquared` number, nullable, required
      - `observationCount` integer, nullable, required
      - `method` 'materialized_factor_exposure_regression_beta', required
    - `rollingBetaCount` integer
    - `rollingBetasUnavailableReason` string, 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[]
    - `export` PortfolioAttributionExport, required
      - `object` 'portfolio_attribution_export', required
      - `requestedFormat` 'json' | 'csv' | 'both', required
      - `formats` string[], required
      - `fileName` string, required
      - `columns` string[], required
      - `csv` string, nullable, required
      - `files` PortfolioAttributionExportFile[], required
        - `name` string, required
        - `kind` 'contributions' | 'return_stream' | 'rolling_betas', required
        - `format` 'csv', required
        - `columns` string[], required
        - `csv` string, required
    - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs.
    - `summaryMd` string, required
    - `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
  - `hedge` PortfolioHedge, required
    - `dataAsOf` string
    - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
    - `methodologyVersion` string
    - `materializationVersion` string
    - `object` 'portfolio_hedge', 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
    - `analysisId` string, nullable, required
    - `asOf` string, date-time, required
    - `country` string, required
    - `lookback` string, required
    - `objective` 'factor_neutral' | 'min_drawdown' | 'regime_aware', required
    - `mode` 'compact' | 'standard', required
    - `constraints` PortfolioHedgeConstraints, required
      - `maxHedges` integer
      - `maxPositionWeight` number
      - `maxTotalHedgeWeight` number
      - `maxSectorWeight` number
      - `hedgeIntensity` number
      - `longOnly` boolean
      - `allowedInstrumentTypes` PortfolioHedgeInstrumentType[]
      - `customUniverse` string[]
      - `targetExposures` object
      - `minConfidence` 'low' | 'medium' | 'high'
      - `minLiquidityUsd` number
      - `excludedSectors` string[]
    - `holdings` PortfolioHoldingInput[], required
      - `symbol` string, required
      - `weight` number, required
      - `shares` number, nullable
      - `costBasis` number, nullable
    - `targetExposures` PortfolioHedgeTargetExposure[], required
      - `object` 'portfolio_hedge_target_exposure', required
      - `factorKey` string, required
      - `factorName` string, required
      - `factorCategory` string, required
      - `beta` number, required
      - `targetExposureDelta` number, required
      - `proposedExposureDelta` number, required
      - `residualBeta` number, required
      - `hedged` boolean, required
      - `skipReason` string, nullable, required
    - `hedges` PortfolioHedgeCandidate[], required
      - `object` 'portfolio_hedge_candidate', required
      - `rank` integer, required
      - `factorKey` string, required
      - `factorName` string, required
      - `factorCategory` string, required
      - `symbol` string, required
      - `instrumentType` 'equity' | 'etf' | 'future' | 'option' | 'cash', required
      - `action` 'long' | 'short', required
      - `recommendedWeight` number, required
      - `targetExposureDelta` number, required
      - `expectedExposureDelta` object, required
      - `residualBeta` number, required
      - `constraintStatus` 'ok' | 'capped', required
      - `constraintsApplied` string[], required
      - `liquidityUsd` number, nullable, required
      - `estimatedCostBps` number, nullable, required
      - `sectorKey` string, nullable, required
      - `rationale` string, required
      - `confidence` 'high' | 'medium' | 'low', required
    - `residualExposure` object, required
    - `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[]
    - `optimizationNotes` string[], required
    - `factorNeutralPlan` string[], required
    - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs.
    - `summaryMd` string, required
    - `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
  - `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[]
  - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs.
  - `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[]
  - `summaryMd` string, required
  - `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)