---
title: "Factor pair spreads"
method: GET
path: "/v1/factors/pairs"
---

# Factor pair spreads

`GET /v1/factors/pairs`

## Request

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

Return pairwise factor spread data including cumulative spread, average, volatility, and daily series for two specified factors.

## Query parameters

- `factor1` string, required
- `factor2` string, required
- `f1` string
- `f2` string
- `window` string
- `lookback` string
- `response_mode` 'compact' | 'standard' | 'verbose'
- `include` string

## Response `200`

Successful response

- FactorPairSpreadList
  - `object` 'list', required
  - `data` union[], required
    - union
      - FactorPairSpread
        - `dataAsOf` string
        - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
        - `methodologyVersion` string
        - `materializationVersion` string
        - `object` 'factor_pair_spread', 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
        - `factor1` string, required
        - `factor2` string, required
        - `factor1Name` string, required
        - `factor2Name` string, required
        - `category1` string, required
        - `category2` string, required
        - `window` string, required
        - `lookback` string, required
        - `spreadReturn` number, required
        - `factor1Return` number, required
        - `factor2Return` number, required
        - `averageSpread` number, required
        - `averageSpreadReturn` number, required
        - `spreadVolatility` number, required
        - `rollingSpreadVolatility` number, required
        - `zScore` number, required
        - `spreadZScore` number, required
        - `absZScore` number, required
        - `direction` 'factor1' | 'factor2' | 'flat', required
        - `meanReversionSignal` 'factor1_overextended' | 'factor2_overextended' | 'neutral', required
        - `meanReversionSummary` string, required
        - `windowStartDate` string, date, required
        - `windowEndDate` string, date, required
        - `rollingObservationCount` integer, required
        - `observationCount` integer, required
        - `series` FactorPairSpreadPoint[], required
          - `date` string, date, required
          - `spread` number, required
          - `f1Return` number, required
          - `f2Return` number, required
        - `asOf` string, date-time, 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[]
      - FactorPairSpreadCompact
        - `dataAsOf` string
        - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
        - `methodologyVersion` string
        - `materializationVersion` string
        - `object` 'factor_pair_spread', 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
        - `factor1` string, required
        - `factor2` string, required
        - `factor1Name` string, required
        - `factor2Name` string, required
        - `category1` string, required
        - `category2` string, required
        - `window` string, required
        - `lookback` string, required
        - `spreadReturn` number, required
        - `factor1Return` number, required
        - `factor2Return` number, required
        - `averageSpread` number, required
        - `averageSpreadReturn` number, required
        - `spreadVolatility` number, required
        - `rollingSpreadVolatility` number, required
        - `zScore` number, required
        - `spreadZScore` number, required
        - `absZScore` number, required
        - `direction` 'factor1' | 'factor2' | 'flat', required
        - `meanReversionSignal` 'factor1_overextended' | 'factor2_overextended' | 'neutral', required
        - `meanReversionSummary` string, required
        - `windowStartDate` string, date, required
        - `windowEndDate` string, date, required
        - `rollingObservationCount` integer, required
        - `observationCount` integer, required
        - `seriesCount` integer, required
        - `seriesSample` FactorPairSpreadPoint[], required
          - `date` string, date, required
          - `spread` number, required
          - `f1Return` number, required
          - `f2Return` number, required
        - `expansionHints` string[], required
        - `asOf` string, date-time, 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[]
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
  - `include` 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)