Skip to main content
This guide maps FactorsToday-style factor-history, valuation, portfolio, hedge, optimizer, dashboard, and bulk-download workflows to SEC API equivalents. Use it as a practical cutover guide for moving factor screens, portfolio analytics, and agent tools onto SEC API’s REST, SDK, CLI, and MCP surfaces.
Start with the user workflow: history tables, 1D through MAX windows, extreme moves, valuation screens, attribution, hedging, optimization, and bulk exports. Then wire the SEC API endpoint that returns the same job with compact responses, request diagnostics, and trust metadata.
For construction details, see Factor Model Methodology. For coverage and freshness semantics, see Factor Provenance and Factor Freshness.

​
What improves when you switch

Agent-first payloads

response_mode=compact keeps factor, portfolio, and model payloads small by default while include=series,trust expands only the fields your workflow needs.

Trust metadata beside the data

Freshness, methodology, materialization, degraded-state, and request diagnostics travel with the response instead of living in a separate support channel.

One surface for REST, SDKs, CLI, and MCP

The same factor workflows are exposed through API reference pages, generated SDKs, CLI commands, and hosted MCP tools for agentic workflows.

Portfolio and model workflows

Attribution, hedging, optimization, stress testing, and model factor analysis share submitted-holdings contracts that work in apps and agents.

​
Endpoint Mapping

FactorsToday workflowSEC APIMigration notes
Factor catalogGET /v1/factors/catalogFactor definitions, category, launch posture, methodology, and source posture.
Basic, style, sector, industry factor tablesGET /v1/factors/catalog?category=style and GET /v1/factors/sparklinesUse catalog for definitions and sparklines for compact chart/table rows.
Daily factor returnsGET /v1/factors/returnsMulti-factor daily return rows with launch-safe defaults.
Intraday factor returnsGET /v1/factors/returns/intradayCurrent only when market-data inputs and snapshot freshness are current.
Single-factor history pageGET /v1/factors/history/{factorKey}Single-factor history with 1D, 5D, 1M, 3M, 6M, 1Y, and MAX summary windows.
Multi-factor history tableGET /v1/factors/sparklinesDownsampled multi-factor series for sector/index/model UI tables.
Manual all-factor return downloadsGET /v1/factors/bulk-downloadBulk daily factor returns for commercial bulk-download workflows; use include=series when full series are needed.
Factor loadings by factorGET /v1/factors/exposures?symbols={symbols}&keys={factor}Exposure loadings for a caller-supplied security universe.
Stock loadings by tickerGET /v1/factors/exposures?symbols={ticker} or GET /v1/stocks/{ticker}/loadingsPer-stock exposure decomposition.
Factor correlationsGET /v1/factors/correlationsLaunch factor correlation matrix.
Factor composition/methodologyGET /v1/factors/catalogEquation, inputs, methodology, source posture, and launch status live on catalog/methodology metadata.
Related stocksGET /v1/factors/related-stocks?symbol={ticker}Factor-similarity stock discovery.
Extreme Factor MovesGET /v1/factors/extreme-movesUnusual factor moves ranked by z-score, absolute return, side, and direction.
Extreme Factor PairsGET /v1/factors/extreme-pairsUnusual factor-pair spread divergence.
Factor ValuationsGET /v1/factors/valuationsFactor-level valuation/opportunity signals.
Factor Valuation StocksGET /v1/factors/valuations/stocksStock candidates exposed to a valuation-factor signal.
Stock screener by factorGET /v1/factors/screenFactor-ranked stock screening.
Portfolio analysisPOST /v1/portfolio/analyzePortfolio factor exposure decomposition from submitted holdings.
Portfolio attributionPOST /v1/portfolio/attributionExplained return, factor contributions, alpha when realized portfolio return is sufficiently covered.
Portfolio hedgePOST /v1/portfolio/hedgeBounded benchmark-instrument hedge candidates and residual exposure.
Portfolio optimizerPOST /v1/portfolio/optimizeFactor-neutral, drawdown-aware, and regime-aware optimizer flows.
Model Builder or model detail factor analysisPOST /v1/models/factor-analysisSubmitted model holdings with exposure, attribution, hedge, optimizer, and position views.
Factor dashboardGET /v1/factors/dashboardOne-call dashboard with intraday, regime, rotation, spotlight, and optional model-portfolio drilldowns.
Regime performanceGET /v1/factors/regime-performanceFactor returns by macro regime.
Portfolio stress testPOST /v1/portfolio/stress-testScenario-based portfolio factor stress testing.
Factor rotationPOST /v1/strategies/factor-rotationFactor rotation signals.

​
Launch Coverage Posture

SEC API’s launch factor surface is built around U.S. market, style, sector, and industry workflows. Launch factors target a 2015-01-01 public history floor, and public history claims should be made only where row-level coverage, freshness, model version, and methodology metadata prove the factor. Shorter-history, beta, blocked, and deferred factors are labeled in catalog or methodology metadata. Do not treat a tracked catalog definition as a launch claim by itself.

​
Workflow Translation Patterns

​
Factor History And Tables

Use factors/history/{factorKey} when the UI focuses on one factor, and factors/sparklines when the UI needs many compact rows for index, sector, dashboard, or model tables. 
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/history/VALUE?range=max&response_mode=compact&include=series,trust"

curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/sparklines?category=sector&range=1y&points=90&response_mode=compact&include=trust"
Use range=max only with the proven row-level floor for that factor. For launch-facing claims, preserve historyStartDate, historyEndDate, observationCount, lastCompleteMarketDate, freshness, materialization, and methodology metadata when present.

​
Bulk Downloads

FactorsToday-style manual return downloads map to GET /v1/factors/bulk-download. Compact mode omits full series unless requested. 
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/bulk-download?category=style&lookback=12m&response_mode=compact&include=series,trust"
Use this endpoint for authorized bulk-download workflows. Use factors/returns, factors/history, or factors/sparklines for UI and agent workflows that do not need a full return export.

​
Extreme Moves And Pairs

Use extreme-move and extreme-pair endpoints for FactorsToday-style homepage views. 
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/extreme-moves?category=style&lookback=6m&limit=20&response_mode=compact&include=trust"

curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/extreme-pairs?category=style&lookback=6m&limit=20&response_mode=compact&include=trust"

​
Valuation Workflows

Use factor valuations for factor-level opportunity discovery and valuation stocks for drilldowns into securities most exposed to a factor signal. 
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/valuations?category=style&signal=tailwind&limit=20&response_mode=compact&include=trust"

curl -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&include=trust"

​
Portfolio, Hedge, And Optimizer

SEC API portfolio endpoints use submitted holdings. Migrate query-string portfolio workflows into POST bodies so agents, SDKs, and UI clients share one contract. 
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&include=trust"

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","objective":"factor_neutral","maxHedges":3}' \
  "https://api.secapi.ai/v1/portfolio/optimize?response_mode=compact&include=trust"
For hedge-specific constraints such as maxPositionWeight, use POST /v1/portfolio/hedge with a constraints object. Unsupported constraints are rejected or returned as explicit degraded state rather than silently modeled.

​
SDK, CLI, And MCP Migration

REST is the fastest path to verify parity. Once the response shape is correct, move application code to the SDK or CLI surface that matches your runtime. 
import { SecApiClient } from "@secapi/sdk-js"

const client = new SecApiClient({ apiKey: process.env.SECAPI_API_KEY })

const history = await client.factorHistory("VALUE", {
  range: "1y",
  response_mode: "compact",
  include: "series,trust",
})

secapi factors history --factor VALUE --range 1y --response-mode compact --include series,trust
secapi portfolio optimize --holdings-file portfolio.json --objective factor_neutral --constraints-json '{"maxCandidates":3}'
Hosted MCP tools mirror the same factor workflow surface. For factor MCP tools that expose response controls, pass response_mode and include with the same intent as REST: compact by default, with trust metadata when an agent will cite freshness, coverage, or methodology. 
{
  "name": "factors.history",
  "arguments": {
    "factorKey": "VALUE",
    "range": "1y",
    "response_mode": "compact",
    "include": ["trust"]
  }
}
Key MCP names include factors.returns, factors.history, factors.sparklines, factors.extreme_moves, factors.extreme_pairs, factors.valuations, factors.valuation_stocks, factors.exposures, factors.bulk_returns, portfolio.analyze, portfolio.attribution, portfolio.hedge, portfolio.optimize, and portfolio.stress_test.

​
Authentication

FactorsToday examples often pass API keys as query parameters. SEC API uses the x-api-key header: 
# SEC API
curl -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/factors/catalog"

​
Migration Checklist

  • Replace query-parameter API keys with the x-api-key header.
  • Replace local return-file jobs with factors/history, factors/sparklines, factors/returns, or factors/bulk-download depending on the UI/export requirement.
  • Use response_mode=compact by default for agent/UI flows.
  • Add include=trust when the workflow needs freshness, materialization, methodology, or degraded-state metadata.
  • Use include=series only when a full daily series is required.
  • Gate MAX and long-history claims on returned row-level coverage and freshness fields.
  • Preserve requestId and traceparent in logs, agent responses, and support tickets.
  • Pin secapi-version before dual-running production traffic.

Factor quickstart

Start with copy-paste factor history, valuation, portfolio, and MCP examples.

Factor API reference

Open the generated REST operation pages for every factor endpoint.

Portfolio analytics

Wire attribution, hedging, optimization, stress testing, and model analysis workflows.