> ## 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/history/{factorKey}

> Return a single factor's daily return history with 1D through MAX summary windows for chart and table workflows

Return a single factor's daily return history with 1D through MAX summary windows for chart and table workflows

<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/history/VALUE?range=1y&response_mode=compact&include=trust"
  ```
</RequestExample>

## Example response

<ResponseExample>
  ```json theme={null}
  {
    "object": "factor_history",
    "id": "factor_history:VALUE:1y:2026-06-09",
    "factorKey": "VALUE",
    "factorName": "Value",
    "category": "style",
    "range": "1y",
    "dateFrom": "2025-06-10",
    "dateTo": "2026-06-09",
    "historyStartDate": "2015-01-02",
    "historyEndDate": "2026-06-09",
    "observationCount": 252,
    "asOf": "2026-06-09T22:15:00.000Z",
    "series": [],
    "seriesCount": 252,
    "seriesSample": [
      {
        "date": "2025-06-10",
        "rawReturn": 0.0012,
        "pureReturn": 0.0009,
        "scaledReturn": 0.0011,
        "zScore": 0.18,
        "leverage": 1
      },
      {
        "date": "2026-06-09",
        "rawReturn": 0.0038,
        "pureReturn": 0.0031,
        "scaledReturn": 0.0042,
        "zScore": 1.42,
        "leverage": 1
      }
    ],
    "expansionHints": [
      "Use include=series for full daily observations in compact mode."
    ],
    "summaryWindows": [
      {
        "window": "1d",
        "rawReturn": 0.0038,
        "pureReturn": 0.0031,
        "scaledReturn": 0.0042,
        "observationCount": 1,
        "startDate": "2026-06-09",
        "endDate": "2026-06-09"
      },
      {
        "window": "1m",
        "rawReturn": 0.018,
        "pureReturn": 0.014,
        "scaledReturn": 0.021,
        "observationCount": 21,
        "startDate": "2026-05-11",
        "endDate": "2026-06-09"
      },
      {
        "window": "max",
        "rawReturn": 1.46,
        "pureReturn": 1.12,
        "scaledReturn": 1.31,
        "observationCount": 2882,
        "startDate": "2015-01-02",
        "endDate": "2026-06-09"
      }
    ],
    "qualityProof": {
      "object": "factor_quality_proof",
      "status": "ready",
      "proofSource": "secapi_factor_pipeline",
      "proofObservedAt": "2026-06-09T22:15:00.000Z",
      "rowLevelProofAvailable": true,
      "proofReady": true,
      "firstDate": "2015-01-02",
      "lastDate": "2026-06-09",
      "firstRequiredMarketDate": "2015-01-02",
      "latestMarketDay": "2026-06-09",
      "targetHistoryStartDate": "2015-01-01",
      "requiredHistoryStartDate": "2015-01-01",
      "shortHistoryExempt": false,
      "historyStartMarketDayLag": 0,
      "latestMarketDayLag": 0,
      "rowCount": 2882,
      "distinctFactorDateCount": 2882,
      "coveredMarketDateCount": 2882,
      "expectedMarketDateCount": 2882,
      "missingSessionCount": 0,
      "coveragePct": 1,
      "methodologyVersion": "secapi_factor_returns_v1",
      "modelName": "secapi_stock_basket_factor_model_v1",
      "methodologyUrl": "https://docs.secapi.ai/factors/methodology",
      "sourceMetadata": {
        "latestAsOf": "2026-06-09",
        "latestSourcePublishedAt": "2026-06-09T21:30:00.000Z",
        "observedModelNameCount": 1,
        "observedModelNamesSample": [
          "secapi_stock_basket_factor_model_v1"
        ],
        "nonStockBasketRowCount": 0,
        "metadataModelNames": [
          "secapi_stock_basket_factor_model_v1"
        ],
        "metadataModelVersions": [
          "2026-06-09"
        ],
        "metadataMethodologyUrls": [
          "https://docs.secapi.ai/factors/methodology"
        ]
      },
      "degradedReasons": []
    },
    "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,
    "requestId": "req_2ZK8Q1W9F4M6P7R3",
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
  }
  ```
</ResponseExample>

## CSV export 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/history/VALUE?range=max&format=csv"
  ```
</RequestExample>

## CSV response

<ResponseExample>
  ```csv theme={null}
  factor_key,factor_name,category,range,date_from,date_to,history_start_date,history_end_date,observation_count,as_of,date,raw_return,pure_return,scaled_return,z_score,leverage,materialization_version,methodology_id,methodology_version,data_as_of
  VALUE,Value,style,max,2015-01-02,2026-06-09,2015-01-02,2026-06-09,2882,2026-06-09T22:15:00.000Z,2026-06-09,0.0038,0.0031,0.0042,1.42,1,2026-06-09,secapi_factor_returns,v1,2026-06-09T22:15:00.000Z
  ```
</ResponseExample>

## Give this prompt to your agent

<Prompt>
  Use SEC API GET /v1/factors/history/{factorKey} when a workflow needs one factor's 1D through MAX return table, chart series, or backtest input. Preserve `factorKey`, `factorName`, `range`, `historyStartDate`, `historyEndDate`, `observationCount`, `seriesSample`, `summaryWindows`, `qualityProof`, `freshness`, `materialization`, `methodology`, `requestId`, and `traceparent`. Use `include=series` only when the downstream table or export needs every daily row.
</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