Factor Intelligence

​

What Factor Intelligence Covers

​

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

​

Categories

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

​

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

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 and pairs

• extreme factor moves ranked by z-score, return, direction, and threshold
• extreme factor pairs ranked by unusual spread divergence

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"

​

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

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

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

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 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

​

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