> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/factors/pairs

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

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

<Info>
  Audience: application and coding agent.
</Info>

## Canonical metadata

* `requestId`
* `traceparent`

## Example request

<RequestExample>
  ```bash theme={null}
  curl -X GET \
    -H "x-api-key: $SECAPI_API_KEY" \
    -H "secapi-version: 2026-03-19" \
    "https://api.secapi.ai/v1/factors/pairs?factor1=VALUE&factor2=MOMENTUM&response_mode=compact&include=trust"
  ```
</RequestExample>

## Example response

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "factor_pair_spread",
        "id": "factor_pair_spread:MOMENTUM:VALUE:21d:2026-06-09",
        "factor1": "MOMENTUM",
        "factor2": "VALUE",
        "factor1Name": "Momentum",
        "factor2Name": "Value",
        "category1": "style",
        "category2": "style",
        "window": "21d",
        "lookback": "6m",
        "spreadReturn": 0.043,
        "factor1Return": 0.064,
        "factor2Return": 0.021,
        "averageSpread": 0.006,
        "averageSpreadReturn": 0.006,
        "spreadVolatility": 0.017,
        "rollingSpreadVolatility": 0.017,
        "zScore": 2.18,
        "spreadZScore": 2.18,
        "absZScore": 2.18,
        "direction": "factor1",
        "meanReversionSignal": "factor1_overextended",
        "meanReversionSummary": "Momentum has outperformed value unusually over the latest 21 trading days.",
        "windowStartDate": "2026-05-11",
        "windowEndDate": "2026-06-09",
        "rollingObservationCount": 106,
        "observationCount": 126,
        "seriesCount": 106,
        "seriesSample": [
          {
            "date": "2026-05-11",
            "spread": 0.004,
            "f1Return": 0.006,
            "f2Return": 0.002
          },
          {
            "date": "2026-06-09",
            "spread": 0.043,
            "f1Return": 0.064,
            "f2Return": 0.021
          }
        ],
        "expansionHints": [
          "Use response_mode=standard for full pair-history series."
        ],
        "asOf": "2026-06-09T22:15:00.000Z",
        "responseMode": "compact",
        "dataAsOf": "2026-06-09",
        "freshnessStatus": "fresh",
        "methodologyVersion": "secapi_factor_returns_v1",
        "materializationVersion": "2026-06-09",
        "provenance": {
          "source": "secapi_factor_pipeline",
          "sourceLabel": "SecAPI factor pipeline",
          "accessionNumber": null,
          "filingUrl": "https://docs.secapi.ai/factors/methodology",
          "acceptedAt": null,
          "retrievedAt": "2026-06-09T22:15:00.000Z",
          "parserVersion": "secapi-factor-pipeline"
        },
        "freshness": {
          "status": "fresh",
          "asOf": "2026-06-09T22:15:00.000Z",
          "sourcePublishedAt": "2026-06-09T21:30:00.000Z",
          "lagMs": 2700000
        },
        "materialization": {
          "parserVersion": "secapi-factor-pipeline",
          "materializationVersion": "2026-06-09"
        },
        "sourceRights": {
          "source": "secapi_owned_factor_pipeline",
          "sourceLabel": "SecAPI factor pipeline",
          "posture": "public_safe",
          "publicAvailability": "public",
          "contractStatus": "approved",
          "restrictions": [],
          "notes": "SecAPI-owned derived factor data."
        },
        "methodology": {
          "id": "secapi_factor_returns",
          "version": "v1",
          "summary": "SecAPI-owned daily factor returns, exposures, and portfolio analytics built for agent and API workflows.",
          "confidence": "high",
          "launchState": "beta",
          "inputs": [
            "secapi_factor_returns",
            "secapi_factor_exposures",
            "market_calendar"
          ],
          "validation": {
            "launchHistoryFloor": "2015-01-01",
            "marketCalendarAware": true
          }
        },
        "revision": {
          "sourcePublishedAt": "2026-06-09T21:30:00.000Z",
          "retrievedAt": "2026-06-09T22:15:00.000Z",
          "vintageId": "2026-06-09",
          "revisedFrom": null
        },
        "degradedState": null
      }
    ],
    "hasMore": false,
    "nextCursor": null,
    "responseMode": "compact",
    "requestId": "req_2ZK8Q1W9F4M6P7R3",
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
  }
  ```
</ResponseExample>

## Give this prompt to your agent

<Prompt>
  Use SEC API GET /v1/factors/pairs to return pairwise factor spread data including cumulative spread, average, volatility, and daily series for two specified factors. Preserve `requestId`, `traceparent` in the output. Return a concise markdown summary plus the exact structured payload fields that a downstream engineer or agent should keep using this result.
</Prompt>

## Failure posture

* treat non-2xx responses as contract-aware failures, not free-form errors
* preserve `requestId` and `traceparent` in logs and downstream reports
* if provenance or freshness metadata is present, return it unchanged so trust is not lost in the handoff