Migrate from FactorsToday

This guide maps FactorsToday-style factor-history, portfolio, hedge, optimizer, dashboard, and bulk-download workflows to SEC API equivalents. Use it as a practical cutover guide for moving factor-ranked workflows, 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, 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 workflow	SEC API	Migration notes
Factor catalog	`GET /v1/factors/catalog`	Factor definitions, category, launch posture, methodology, and source posture.
Basic, style, sector, industry factor tables	`GET /v1/factors/catalog?category=style` and `GET /v1/factors/sparklines`	Use catalog for definitions and sparklines for compact chart/table rows.
Daily factor returns	`GET /v1/factors/returns`	Multi-factor daily return rows with launch-safe defaults.
Intraday factor returns	`GET /v1/factors/returns/intraday`	Current only when market-data inputs and snapshot freshness are current.
Single-factor history page	`GET /v1/factors/history/{factorKey}`	Single-factor history with 1D, 5D, 1M, 3M, 6M, 1Y, and MAX summary windows.
Multi-factor history table	`GET /v1/factors/sparklines`	Downsampled multi-factor series for sector/index/model UI tables.
Manual all-factor return downloads	`GET /v1/factors/bulk-download`	Bulk daily factor returns for commercial bulk-download workflows; use `include=series` when full series are needed.
Factor loadings by factor	`GET /v1/factors/exposures?symbols={symbols}&keys={factor}`	Exposure loadings for a caller-supplied security universe.
Stock loadings by ticker	`GET /v1/factors/exposures?symbols={ticker}` or `GET /v1/stocks/{ticker}/loadings`	Per-stock exposure decomposition.
Factor correlations	`GET /v1/factors/correlations`	Launch factor correlation matrix.
Factor composition/methodology	`GET /v1/factors/catalog`	Equation, inputs, methodology, source posture, and launch status live on catalog/methodology metadata.
Related stocks	`GET /v1/factors/related-stocks?symbol={ticker}`	Factor-similarity stock discovery.
Extreme Factor Moves	`GET /v1/factors/extreme-moves`	Unusual factor moves ranked by z-score, absolute return, side, and direction.
Extreme Factor Pairs	`GET /v1/factors/extreme-pairs`	Unusual factor-pair spread divergence.
Portfolio analysis	`POST /v1/portfolio/analyze`	Portfolio factor exposure decomposition from submitted holdings.
Portfolio attribution	`POST /v1/portfolio/attribution`	Explained return, factor contributions, alpha when realized portfolio return is sufficiently covered.
Portfolio hedge	`POST /v1/portfolio/hedge`	Bounded benchmark-instrument hedge candidates and residual exposure.
Portfolio optimizer	`POST /v1/portfolio/optimize`	Factor-neutral, drawdown-aware, and regime-aware optimizer flows.
Model Builder or model detail factor analysis	`POST /v1/models/factor-analysis`	Submitted model holdings with exposure, attribution, hedge, optimizer, and position views.
Factor dashboard	`GET /v1/factors/dashboard`	One-call dashboard with intraday, regime, rotation, spotlight, and optional model-portfolio drilldowns.
Regime performance	`GET /v1/factors/regime-performance`	Factor returns by macro regime.
Portfolio stress test	`POST /v1/portfolio/stress-test`	Scenario-based portfolio factor stress testing.
Factor rotation	`POST /v1/strategies/factor-rotation`	Factor 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"

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

Plans & pricing

Products

Workflow guides

Concepts & trust

Tutorials

Migrate to SEC API

Solutions

Compare

API guides by topic

What improves when you switch

Agent-first payloads

Trust metadata beside the data

One surface for REST, SDKs, CLI, and MCP

Portfolio and model workflows

Endpoint Mapping

Launch Coverage Posture

Workflow Translation Patterns

Factor History And Tables

Bulk Downloads

Extreme Moves And Pairs

Portfolio, Hedge, And Optimizer

SDK, CLI, And MCP Migration

Authentication

Migration Checklist

Read next

Factor quickstart

Factor API reference

Portfolio analytics

​What improves when you switch

Agent-first payloads

Trust metadata beside the data

One surface for REST, SDKs, CLI, and MCP

Portfolio and model workflows

​Endpoint Mapping

​Launch Coverage Posture

​Workflow Translation Patterns

​Factor History And Tables

​Bulk Downloads

​Extreme Moves And Pairs

​Portfolio, Hedge, And Optimizer

​SDK, CLI, And MCP Migration

​Authentication

​Migration Checklist

​Read next

Factor quickstart

Factor API reference

Portfolio analytics

What improves when you switch

Endpoint Mapping

Launch Coverage Posture

Workflow Translation Patterns

Factor History And Tables

Bulk Downloads

Extreme Moves And Pairs

Portfolio, Hedge, And Optimizer

SDK, CLI, And MCP Migration

Authentication

Migration Checklist

Read next