> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from FactorsToday

> Map FactorsToday factor-history, valuation, portfolio, hedge, and bulk-export workflows to their SEC API equivalents for a smooth cutover.

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.

<Info>
  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.
</Info>

For construction details, see [Factor Model Methodology](/factor-model-methodology). For coverage and freshness semantics, see [Factor Provenance](/factor-provenance) and [Factor Freshness](/factor-freshness).

## What improves when you switch

<CardGroup cols={2}>
  <Card title="Agent-first payloads" icon="bot" href="/api-conventions">
    `response_mode=compact` keeps factor, portfolio, and model payloads small by default while `include=series,trust` expands only the fields your workflow needs.
  </Card>

  <Card title="Trust metadata beside the data" icon="shield-check" href="/factor-freshness">
    Freshness, methodology, materialization, degraded-state, and request diagnostics travel with the response instead of living in a separate support channel.
  </Card>

  <Card title="One surface for REST, SDKs, CLI, and MCP" icon="blocks" href="/mcp-workflows">
    The same factor workflows are exposed through API reference pages, generated SDKs, CLI commands, and hosted MCP tools for agentic workflows.
  </Card>

  <Card title="Portfolio and model workflows" icon="chart-no-axes-combined" href="/portfolio-analytics">
    Attribution, hedging, optimization, stress testing, and model factor analysis share submitted-holdings contracts that work in apps and agents.
  </Card>
</CardGroup>

## 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.                                                                              |
| Factor Valuations                             | `GET /v1/factors/valuations`                                                       | Factor-level valuation/opportunity signals.                                                                         |
| Factor Valuation Stocks                       | `GET /v1/factors/valuations/stocks`                                                | Stock candidates exposed to a valuation-factor signal.                                                              |
| Stock screener by factor                      | `GET /v1/factors/screen`                                                           | Factor-ranked stock screening.                                                                                      |
| 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```ts theme={null}
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",
})
```

```bash theme={null}
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.

```json theme={null}
{
  "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:

```bash theme={null}
# 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.

## Read next

<CardGroup cols={3}>
  <Card title="Factor quickstart" icon="square-terminal" href="/factor-quickstart">
    Start with copy-paste factor history, valuation, portfolio, and MCP examples.
  </Card>

  <Card title="Factor API reference" icon="braces" href="/api-reference/factors">
    Open the generated REST operation pages for every factor endpoint.
  </Card>

  <Card title="Portfolio analytics" icon="chart-pie" href="/portfolio-analytics">
    Wire attribution, hedging, optimization, stress testing, and model analysis workflows.
  </Card>
</CardGroup>