> ## 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. # Factor Quickstart > Make the first useful factor data requests with REST, SDKs, and hosted MCP. Use this path when you want compact factor catalog, returns, history, and portfolio attribution data in a product or agent workflow. ## Before you start 1. Export `SECAPI_API_KEY` 2. Use `https://api.secapi.ai` for production requests 3. Send the API key in the `x-api-key` header 4. Send `secapi-version: 2026-03-19` 5. Use `response_mode=compact&include=trust` for agent, chart, table, and prompt-context workflows that need audit metadata Keep `requestId`, `traceparent`, `freshness`, `materialization`, `methodology`, and `degradedState` fields attached to downstream traces when they are present. If a compact response omits a heavier section your workflow needs, request it with `include`; those fields tell an agent whether the answer is current, how it was constructed, and whether any part of the response fell back to a partial state. ## REST Start with the catalog, then request the smallest return window that proves your workflow. ```bash theme={null} curl -H "x-api-key: $SECAPI_API_KEY" \ -H "secapi-version: 2026-03-19" \ "https://api.secapi.ai/v1/factors/catalog?category=style" curl -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&include=trust" ``` Use single-factor history when you need a 1D through MAX table, chart, or backtest input. ```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=1y&response_mode=compact&include=trust" ``` Use extreme-move endpoints when you need to investigate unusual factor behavior instead of just return history. ```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&window=1d&min_z_score=2&limit=10&response_mode=compact&include=trust" ``` ## TypeScript ```bash theme={null} npm install @secapi/sdk-js ``` ```ts theme={null} import { SecApiClient } from "@secapi/sdk-js" const client = new SecApiClient({ apiKey: process.env.SECAPI_API_KEY!, }) const returns = await client.factorReturns({ keys: ["VALUE", "MOMENTUM", "QUALITY"], lookback: "6m", response_mode: "compact", include: ["trust"], }) const history = await client.factorHistory("VALUE", { range: "1y", response_mode: "compact", include: ["trust"], }) console.log({ requestId: returns.requestId, factors: returns.data, historySample: history.seriesSample, windows: history.summaryWindows, }) ``` ## Python ```bash theme={null} pip install secapi-client ``` ```python theme={null} import os from secapi_client import SecApiClient client = SecApiClient( api_key=os.environ["SECAPI_API_KEY"], base_url="https://api.secapi.ai", ) returns = client.factor_returns( keys=["VALUE", "MOMENTUM", "QUALITY"], lookback="6m", response_mode="compact", include=["trust"], ) history = client.factor_history( "VALUE", range="1y", response_mode="compact", include=["trust"], ) print({ "requestId": returns["requestId"], "factors": returns.get("data"), "historySample": history.get("seriesSample"), "windows": history.get("summaryWindows"), }) ``` ## Portfolio Attribution Use portfolio attribution when you need explained return, residual alpha, contribution rows, and model metadata for a portfolio or model-builder draft. ```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" ``` ```ts theme={null} const attribution = await client.portfolioAttribution( { 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", }, { response_mode: "compact", include: ["trust"] }, ) ``` ```python theme={null} attribution = client.portfolio_attribution( { "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", }, params={"response_mode": "compact", "include": ["trust"]}, ) ``` ## Hosted MCP Hosted MCP exposes the same factor workflows as agent-callable tools. ```bash theme={null} claude mcp add --transport streamable-http sec-api https://api.secapi.ai/mcp \ --header "x-api-key: $SECAPI_API_KEY" ``` Call compact factor returns: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "factors.returns", "arguments": { "keys": ["VALUE", "MOMENTUM", "QUALITY"], "lookback": "6m", "response_mode": "compact", "include": ["trust"] } } } ``` Call portfolio attribution: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "portfolio.attribution", "arguments": { "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", "response_mode": "compact", "include": ["trust"] } } } ``` Use SEC API hosted MCP to get VALUE, MOMENTUM, and QUALITY factor returns for the last 6 months, fetch VALUE history for 1 year, identify the largest style-factor extreme moves, and attribute this portfolio to style factors: AAPL 30%, MSFT 25%, NVDA 20%, JPM 15%, XOM 10%. Request compact responses with `include: ["trust"]`, then return requestId, traceparent, freshness, materialization, methodology, and degradedState with the answer. ## Next Pages * [Factor Intelligence](/factor-intelligence) * [Factor Model Methodology](/factor-model-methodology) * [Factor Provenance](/factor-provenance) * [Factor Freshness](/factor-freshness) * [Hosted MCP Workflows](/mcp-workflows) * [Migrate from FactorsToday](/migrate-from-factorstoday)