---
title: "Portfolio return attribution"
method: POST
path: "/v1/portfolio/attribution"
---

# Portfolio return attribution

`POST /v1/portfolio/attribution`

## Request

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

Return factor return attribution for a portfolio with explained return, residual/unexplained return, and compact contribution rows.

## Query parameters

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

## Request body

- PortfolioAttributionRequest
  - `country` string
  - `lookback` string
  - `window` string
  - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annual'
  - `exportFormat` 'json' | 'csv' | 'both'
  - `category` string
  - `keys` string[]
  - `holdings` PortfolioHoldingInput[], required
    - `symbol` string, required
    - `weight` number, required
    - `shares` number, nullable
    - `costBasis` number, nullable
  - `mode` 'factor' | 'brinson'
  - `benchmark` 'SPY' | 'ACWX' | 'QQQ' | 'IWM' | 'SIXTY_FORTY'
  - `benchmarkSectors` object[]
    - `sector` string, required
    - `portfolioWeight` number, required
    - `benchmarkWeight` number, required
    - `portfolioReturn` number, required
    - `benchmarkReturn` number, required

## Response `200`

Successful response

- PortfolioAttribution
  - `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

## 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)