Skip to main content

​
Factor Provenance

Factor responses are designed to be auditable after they leave the API. Use include=trust on compact requests when an agent, workflow, or report needs the provenance and methodology envelope.
SEC API factor data is produced from SecAPI-owned models, public-company data, market-data inputs available to SEC API, and documented proxy or basket definitions. The product goal is FactorsToday-compatible workflows with SecAPI-owned data and methodology, not copying another provider’s datasets.

​
What To Preserve

Every factor workflow should preserve these fields when they are present:
FieldWhy it matters
requestIdSupport can trace the exact API request.
traceparentDistributed traces can connect API, MCP, SDK, and downstream application work.
freshnessTells you whether the response is fresh, stale, degraded, or unknown for the requested clock.
materializationIdentifies the parser, model, or read-model version that produced the response.
methodologyIdentifies the model family, inputs, and construction notes when included.
sourceRightsDescribes whether the source posture is public-safe, contract-gated, or otherwise restricted.
degradedStateExplains partial responses without pretending the workflow is complete.
Compact factor responses optimize for agent and chart payload size. If your workflow needs trust metadata, request it explicitly: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/returns?keys=VALUE,MOMENTUM,QUALITY&lookback=6m&response_mode=compact&include=trust"
For MCP, pass the same include intent: 
{
  "name": "factors.returns",
  "arguments": {
    "keys": ["VALUE", "MOMENTUM", "QUALITY"],
    "lookback": "6m",
    "response_mode": "compact",
    "include": ["trust"]
  }
}

​
Source Posture

Factor familyLaunch posture
Market factorBuilt from SecAPI market-data inputs and benchmark construction metadata.
Style factorsBuilt from point-in-time security returns and public-company characteristics such as SEC-derived fundamentals when used by the factor definition.
Sector and industry factorsBuilt from point-in-time security returns plus public classification mappings such as SIC-derived sector and industry groupings.
Portfolio attribution and hedgeBuilt from the portfolio holdings submitted by the caller plus SecAPI factor exposure and return read models.
Thematic, country, and macro tracked definitionsTracked in the catalog or methodology registry, but not all are part of the launch-read default surface or 2010+ claim set.
Do not treat a tracked catalog definition as a launch claim by itself. The launch claim boundary is determined by row-level materialization, freshness, model/version metadata, and source-rights posture.

​
Materialization Versions

Common factor materialization identifiers include:
Identifier patternMeaning
factor_returns_clickhouse_v2_stock_basketDaily factor returns served from the stock-basket ClickHouse read model.
factor_returns_clickhouse_v2_purifiedDaily factor returns served from the purified factor-return read model.
factor_exposures_latest_v2_stock_basketLatest security exposure read model for stock-basket factors.
factor_exposures_latest_v2_purifiedLatest security exposure read model for purified factors.
portfolio_factor_attribution_v1Portfolio attribution assembled from holdings, exposures, and realized factor returns.
portfolio_factor_hedge_v1Portfolio hedge suggestions assembled from portfolio factor exposure targets and hedge constraints.
These identifiers are operational contracts. They let you tell whether a result came from a materialized read model, a computed fallback, or an explicit degraded path.

​
How Degraded States Work

A degraded response is still a structured response. It should be handled differently from a silent success and differently from a generic error. Common examples:
  • factor returns are unavailable because a required read model is not materialized
  • portfolio attribution is partial because some holdings lack sufficient market bars
  • hedge suggestions are empty because factor exposures are missing or constraints reject all candidates
  • intraday factor state is stale because market-data inputs are not current
Preserve degradedState.code, degradedState.message, degradedState.retryable, degradedState.missingCapabilities, and degradedState.fallbackUsed when present. Some materialization error details may also include operatorAction; preserve it when it appears outside the degraded-state envelope.

​
Next Pages