Factor Intelligence - SEC API for AI

Factor Intelligence is in beta — the compute methodology is still being validated. All factor responses carry the SECAPI-Maturity: beta response header; do not yet treat returned values as production-grade.

What Factor Intelligence Covers

SEC API Factor Intelligence provides a structured factor model for launch-focused U.S. market, style, sector, and industry workflows. The API supports factor catalog retrieval, single-factor history, multi-factor sparklines, historical and intraday returns, extreme move detection, valuation signals, correlation analysis, per-stock exposure loadings, regime-conditioned performance, portfolio decomposition, and consolidated dashboard views. Every response includes requestId and traceparent for downstream traceability. For the full factor construction methodology, including purification architecture, academic references, and institutional comparisons, see Factor Model Methodology. For source posture and freshness contracts, see Factor Provenance and Factor Freshness.

Factor catalog

launch-focused factors are organized into market, style, sector, and industry categories
each factor entry includes methodology description, source status, proxy or construction metadata, orthogonalization metadata, and category assignment
the catalog is the canonical reference for factor identifiers used across all other factor endpoints
launch factors target a 2015-01-01 public history floor; shorter-history or beta factors are labeled as such and should not be used for unsupported coverage claims

Category	Description
`market`	broad market risk premia (e.g., equity risk premium, volatility)
`style`	cross-sectional return drivers (e.g., momentum, value, quality, size, low-volatility)
`sector`	GICS sector-level return attribution
`industry`	GICS industry-level return attribution

Factor returns

historical daily factor return series with z-scores and volatility-scaled variants
supports filtering by factor category, individual factor identifiers, and date range
used for backtesting, trend analysis, and factor-timing research
use response_mode=compact when forwarding results into an agent, chart, or table workflow

Query parameters

Parameter	Type	Description
`keys`	string	comma-separated list of factor identifiers
`category`	string	filter by launch factor category (`market`, `style`, `sector`, `industry`)
`window`	string	return window such as `1d`, `1m`, `6m`, `1y`, or `max`
`lookback`	string	alternate lookback window alias used by SDK and agent workflows
`response_mode`	string	response shape (`compact`, `standard`, `verbose`)

curl -X GET \
  -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"

Single-factor history and sparklines

single-factor daily history with 1D through MAX summary windows, bounded by row-level coverage and freshness metadata
compact multi-factor sparkline series for sector, index, model, and dashboard UI views
designed for token-efficient chart/table rendering where the caller needs returns plus window summaries, not full attribution payloads

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"

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/sparklines?keys=VALUE,MOMENTUM,QUALITY&range=1y&points=64&response_mode=compact"

Extreme moves, pairs, and valuations

extreme factor moves ranked by z-score, return, direction, and threshold
extreme factor pairs ranked by unusual spread divergence
valuation-factor opportunity signals and stock candidates exposed to those signals

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/extreme-moves?category=style&window=1d&min_z_score=2&limit=10&response_mode=compact"

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/valuations?signal=tailwind&sort=opportunity_score&limit=1&response_mode=compact"

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/valuations/stocks?factor=VALUE&stance=beneficiaries&limit=25&response_mode=compact"

Factor correlations

factor-to-factor and factor-to-security correlation matrices
supports windowed correlation with configurable lookback
useful for strategy diversification analysis and risk decomposition

Query parameters

Parameter	Type	Description
`keys`	string	comma-separated list of factor identifiers
`category`	string	filter by factor category
`lookback`	string	correlation lookback window such as `3m`, `6m`, or `1y`

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/correlations?keys=VALUE,MOMENTUM,QUALITY&lookback=1y&response_mode=compact"

Factor exposures

per-stock, portfolio, or watchlist factor loadings with model metadata and provenance
exposures reflect the sensitivity of a security’s returns to each factor
supports single-ticker and batch queries

Query parameters

Parameter	Type	Description
`symbols`	string	comma-separated list of security symbols
`tickers`	string	alias for `symbols`
`category`	string	filter exposures to a specific factor category
`keys`	string	comma-separated list of factor identifiers
`lookback`	string	exposure model lookback window
`model`	string	optional exposure model selector

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/exposures?symbols=AAPL&response_mode=compact"

Factor intraday

intraday factor return snapshots derived from the current benchmark proxy inputs when the market-data plane is current
intended for dashboards and real-time factor monitoring during market hours
callers should inspect freshness metadata before treating an intraday snapshot as current

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/returns/intraday"

Factor dashboard

consolidated one-call view combining intraday returns, regime context, rotation signals, and available factor state
designed to power full-screen factor dashboards in a single request

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/dashboard?response_mode=compact"

Factor regime performance

factor rankings conditioned on the current macro regime
blends the active macro backdrop (expansion, contraction, stress, recovery) with current factor state
useful for regime-aware factor rotation and allocation decisions

Query parameters

Parameter	Type	Description
`country`	string	country scope, defaults to `US`
`keys`	string	comma-separated list of factor identifiers
`category`	string	filter by factor category
`window`	string	performance window
`lookback`	string	historical lookback window
`limit`	integer	maximum ranked factors to return
`response_mode`	string	response shape (`compact`, `standard`, `verbose`)

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/regime-performance"

Portfolio factor analysis

decompose an arbitrary portfolio into factor exposures, return attribution, and hedge suggestions
accepts a list of holdings with weights in the request body
returns explained return, residual alpha, and per-factor contribution

curl -X POST \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  -H "content-type: application/json" \
  -d '{
    "holdings": [
      {"symbol": "AAPL", "weight": 0.30},
      {"symbol": "MSFT", "weight": 0.25},
      {"symbol": "GOOGL", "weight": 0.20},
      {"symbol": "AMZN", "weight": 0.15},
      {"symbol": "NVDA", "weight": 0.10}
    ]
  }' \
  "https://api.secapi.ai/v1/portfolio/analyze"

Portfolio attribution and hedge

dedicated attribution endpoint for explained return, alpha, and compact contribution rows
dedicated hedge endpoint for constrained hedge candidates and residual factor exposure
both endpoints accept the same normalized holdings shape used by portfolio analysis

curl -X POST \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  -H "content-type: application/json" \
  -d '{
    "holdings": [
      {"symbol": "AAPL", "weight": 0.30},
      {"symbol": "MSFT", "weight": 0.25},
      {"symbol": "NVDA", "weight": 0.20},
      {"symbol": "JPM", "weight": 0.15},
      {"symbol": "XOM", "weight": 0.10}
    ],
    "lookback": "6m",
    "category": "style"
  }' \
  "https://api.secapi.ai/v1/portfolio/attribution?response_mode=compact"

Model portfolio factor view

factor view scoped to a saved model portfolio
returns aggregate portfolio-level exposures and per-position factor breakdowns
useful for monitoring factor drift and concentration in model portfolios

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/model-portfolios/{portfolioId}/factor-view"

Model factor analysis

ad hoc Model Builder or saved-model holdings analysis without first persisting a model portfolio
optional attribution, hedge, and per-position sections in one compact response
useful for /models and model detail views that need the same factor intelligence as portfolio workflows

curl -X POST \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  -H "content-type: application/json" \
  -d '{
    "model": {"id": "growth-quality-core", "label": "Growth Quality Core", "source": "model_builder"},
    "holdings": [
      {"symbol": "AAPL", "weight": 0.30},
      {"symbol": "MSFT", "weight": 0.25},
      {"symbol": "NVDA", "weight": 0.20},
      {"symbol": "GOOGL", "weight": 0.15},
      {"symbol": "AMZN", "weight": 0.10}
    ],
    "include": {"attribution": true, "hedge": true, "optimizer": true, "positionViews": true},
    "optimizer": {"objective": "min_drawdown", "constraints": {"maxCandidates": 3, "turnoverLimit": 0.25}}
  }' \
  "https://api.secapi.ai/v1/models/factor-analysis?response_mode=compact"

Endpoint summary

Method	Endpoint	Description
`GET`	`/v1/factors/catalog`	list all factor definitions
`GET`	`/v1/factors/returns`	historical factor returns
`GET`	`/v1/factors/history/:factorKey`	single-factor history and summary windows
`GET`	`/v1/factors/sparklines`	compact multi-factor sparkline series
`GET`	`/v1/factors/extreme-moves`	unusual factor move ranking
`GET`	`/v1/factors/extreme-pairs`	unusual factor-pair spread ranking
`GET`	`/v1/factors/valuations`	valuation-factor opportunity signals
`GET`	`/v1/factors/valuations/stocks`	stock candidates exposed to valuation signals
`GET`	`/v1/factors/correlations`	factor correlation matrix
`GET`	`/v1/factors/exposures`	per-stock factor loadings
`GET`	`/v1/factors/returns/intraday`	intraday factor return snapshots
`GET`	`/v1/factors/dashboard`	consolidated factor dashboard
`GET`	`/v1/factors/regime-performance`	factor performance by macro regime
`POST`	`/v1/portfolio/analyze`	portfolio factor decomposition
`POST`	`/v1/portfolio/attribution`	portfolio factor return attribution
`POST`	`/v1/portfolio/hedge`	constrained portfolio hedge candidates
`GET`	`/v1/model-portfolios/:id/factor-view`	model portfolio factor view
`POST`	`/v1/models/factor-analysis`	ad hoc model factor analysis with optional attribution, hedge, and optimizer sections

Errors and partial results

Treat non-2xx responses as API errors and log the response body for debugging
Log requestId and traceparent so SEC API support can trace the request
if provenance or freshness metadata is present, return it unchanged so trust is not lost in the handoff

​What Factor Intelligence Covers

​Factor catalog

​Categories

​Factor returns

​Query parameters

​Single-factor history and sparklines

​Extreme moves, pairs, and valuations

​Factor correlations

​Query parameters

​Factor exposures

​Query parameters

​Factor intraday

​Factor dashboard

​Factor regime performance

​Query parameters

​Portfolio factor analysis

​Portfolio attribution and hedge

​Model portfolio factor view

​Model factor analysis

​Endpoint summary

​Errors and partial results

What Factor Intelligence Covers

Factor catalog

Categories

Factor returns

Query parameters

Single-factor history and sparklines

Extreme moves, pairs, and valuations

Factor correlations

Query parameters

Factor exposures

Query parameters

Factor intraday

Factor dashboard

Factor regime performance

Query parameters

Portfolio factor analysis

Portfolio attribution and hedge

Model portfolio factor view

Model factor analysis

Endpoint summary

Errors and partial results