> ## 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.
# GET /v1/model-portfolios/{portfolioId}/factor-view
> Return a model-portfolio factor view with aggregate analysis and per-position exposures for drill-down workflows
Return a model-portfolio factor view with aggregate analysis and per-position exposures for drill-down workflows
Audience: application and coding agent.
## Canonical metadata
* `requestId`
* `traceparent`
## Example request
```bash theme={null}
curl -X GET \
-H "x-api-key: $SECAPI_API_KEY" \
-H "secapi-version: 2026-03-19" \
"https://api.secapi.ai/v1/model-portfolios/growth-quality-core/factor-view"
```
## Example response
```json theme={null}
{
"object": "model_portfolio_factor_view",
"id": "model_portfolio_factor_view:growth-quality-core:2026-06-09",
"portfolioId": "growth-quality-core",
"label": "Growth Quality Core",
"description": "Saved model portfolio factor view.",
"tags": [
"model-builder",
"growth"
],
"holdings": [
{
"symbol": "AAPL",
"weight": 0.35
},
{
"symbol": "MSFT",
"weight": 0.3
},
{
"symbol": "NVDA",
"weight": 0.2
},
{
"symbol": "JPM",
"weight": 0.15
}
],
"analysis": {
"object": "portfolio_analysis",
"id": "portfolio_analysis:growth-quality-core:2026-06-09",
"asOf": "2026-06-09T22:15:00.000Z",
"holdings": [
{
"symbol": "AAPL",
"weight": 0.35
},
{
"symbol": "MSFT",
"weight": 0.3
},
{
"symbol": "NVDA",
"weight": 0.2
},
{
"symbol": "JPM",
"weight": 0.15
}
],
"exposures": [
{
"object": "factor_exposure",
"id": "factor_exposure:AAPL:VALUE:2026-06-09",
"subjectType": "security",
"subjectKey": "AAPL",
"factorKey": "VALUE",
"beta": -0.42,
"percentile": 18.2,
"confidence": "high",
"modelName": "secapi_stock_basket_factor_model_v1",
"asOf": "2026-06-09T22:15:00.000Z",
"responseMode": "compact",
"expansionHints": [
"Use include=diagnostics or response_mode=standard for regression diagnostics such as rSquared, tStat, and observationCount."
]
}
],
"fit": null,
"benchmarkLabel": "NASDAQ 100",
"benchmarkTilts": [],
"whatIfComparison": null,
"positionViews": [],
"positionExposures": [
{
"object": "factor_exposure",
"id": "factor_exposure:AAPL:VALUE:2026-06-09",
"subjectType": "security",
"subjectKey": "AAPL",
"factorKey": "VALUE",
"beta": -0.42,
"percentile": 18.2,
"confidence": "high",
"modelName": "secapi_stock_basket_factor_model_v1",
"asOf": "2026-06-09T22:15:00.000Z",
"responseMode": "compact",
"expansionHints": [
"Use include=diagnostics or response_mode=standard for regression diagnostics such as rSquared, tStat, and observationCount."
]
}
],
"attribution": [
{
"key": "VALUE",
"label": "Value",
"category": "factor",
"contributionPercent": -0.48,
"explanation": "Negative value beta detracted as value lagged over the selected window."
}
],
"hedgeSuggestions": [
{
"symbol": "VLUE",
"instrumentType": "etf",
"rationale": "Offsets the portfolio's negative value exposure with a liquid value ETF sleeve.",
"expectedExposureDelta": {
"VALUE": 0.18
},
"confidence": "medium"
}
],
"optimizationNotes": [
"Candidate search respected max position and turnover constraints."
],
"factorNeutralPlan": [
"Reduce negative VALUE exposure before increasing MOMENTUM exposure."
],
"optimizerObjective": "factor_neutral",
"optimizerConstraints": {
"maxCandidates": 3,
"maxIterations": 50,
"maxRuntimeMs": 750,
"maxPositionWeight": 0.4,
"minPositionWeight": 0.02,
"longOnly": true,
"turnoverLimit": 0.25,
"riskFreeRate": 0.04
},
"optimizerRuntime": {
"object": "portfolio_optimizer_runtime",
"method": "bounded_deterministic_candidate_search",
"candidateCount": 3,
"iterationBudget": 50,
"iterationsRun": 38,
"runtimeMs": 118,
"maxRuntimeMs": 750,
"timeout": false
},
"optimizerCandidateCount": 1,
"optimizerCandidateSample": [
{
"object": "portfolio_optimizer_candidate",
"rank": 1,
"name": "Factor-neutral tilt",
"objective": "factor_neutral",
"expectedReturn": 0.087,
"expectedVolatility": 0.164,
"expectedSharpe": 0.53,
"maxDrawdownProxy": -0.18,
"factorExposureScore": 0.21,
"turnover": 0.12,
"score": 0.81,
"constraintStatus": "ok",
"constraintsApplied": [
"turnoverLimit"
],
"rationale": "Improves factor balance without breaching turnover or concentration limits."
}
],
"selectedCandidate": null,
"optimizerDisclosures": [
"Optimizer output is a deterministic scenario, not investment advice."
],
"disclosures": [
"Research scenario only. Not investment advice or a recommendation to trade."
],
"summaryMd": "Portfolio is growth and quality tilted with a moderate negative value exposure.",
"responseMode": "compact",
"dataAsOf": "2026-06-09",
"freshnessStatus": "fresh",
"methodologyVersion": "secapi_portfolio_factor_v1",
"materializationVersion": "2026-06-09",
"provenance": {
"source": "secapi_factor_pipeline",
"sourceLabel": "SecAPI factor pipeline",
"accessionNumber": null,
"filingUrl": "https://docs.secapi.ai/factors/methodology",
"acceptedAt": null,
"retrievedAt": "2026-06-09T22:15:00.000Z",
"parserVersion": "secapi-factor-pipeline"
},
"freshness": {
"status": "fresh",
"asOf": "2026-06-09T22:15:00.000Z",
"sourcePublishedAt": "2026-06-09T21:30:00.000Z",
"lagMs": 2700000
},
"materialization": {
"parserVersion": "secapi-factor-pipeline",
"materializationVersion": "2026-06-09"
},
"sourceRights": {
"source": "secapi_owned_factor_pipeline",
"sourceLabel": "SecAPI factor pipeline",
"posture": "public_safe",
"publicAvailability": "public",
"contractStatus": "approved",
"restrictions": [],
"notes": "SecAPI-owned derived factor data."
},
"methodology": {
"id": "secapi_factor_returns",
"version": "v1",
"summary": "SecAPI-owned daily factor returns, exposures, and portfolio analytics built for agent and API workflows.",
"confidence": "high",
"launchState": "beta",
"inputs": [
"secapi_factor_returns",
"secapi_factor_exposures",
"market_calendar"
],
"validation": {
"launchHistoryFloor": "2015-01-01",
"marketCalendarAware": true
}
},
"revision": {
"sourcePublishedAt": "2026-06-09T21:30:00.000Z",
"retrievedAt": "2026-06-09T22:15:00.000Z",
"vintageId": "2026-06-09",
"revisedFrom": null
},
"degradedState": null
},
"positionViews": [],
"positionExposures": [
{
"object": "factor_exposure",
"id": "factor_exposure:AAPL:VALUE:2026-06-09",
"subjectType": "security",
"subjectKey": "AAPL",
"factorKey": "VALUE",
"beta": -0.42,
"percentile": 18.2,
"confidence": "high",
"modelName": "secapi_stock_basket_factor_model_v1",
"asOf": "2026-06-09T22:15:00.000Z",
"responseMode": "compact",
"expansionHints": [
"Use include=diagnostics or response_mode=standard for regression diagnostics such as rSquared, tStat, and observationCount."
]
}
],
"responseMode": "compact",
"dataAsOf": "2026-06-09",
"freshnessStatus": "fresh",
"methodologyVersion": "secapi_factor_returns_v1",
"materializationVersion": "2026-06-09",
"provenance": {
"source": "secapi_factor_pipeline",
"sourceLabel": "SecAPI factor pipeline",
"accessionNumber": null,
"filingUrl": "https://docs.secapi.ai/factors/methodology",
"acceptedAt": null,
"retrievedAt": "2026-06-09T22:15:00.000Z",
"parserVersion": "secapi-factor-pipeline"
},
"freshness": {
"status": "fresh",
"asOf": "2026-06-09T22:15:00.000Z",
"sourcePublishedAt": "2026-06-09T21:30:00.000Z",
"lagMs": 2700000
},
"materialization": {
"parserVersion": "secapi-factor-pipeline",
"materializationVersion": "2026-06-09"
},
"sourceRights": {
"source": "secapi_owned_factor_pipeline",
"sourceLabel": "SecAPI factor pipeline",
"posture": "public_safe",
"publicAvailability": "public",
"contractStatus": "approved",
"restrictions": [],
"notes": "SecAPI-owned derived factor data."
},
"methodology": {
"id": "secapi_factor_returns",
"version": "v1",
"summary": "SecAPI-owned daily factor returns, exposures, and portfolio analytics built for agent and API workflows.",
"confidence": "high",
"launchState": "beta",
"inputs": [
"secapi_factor_returns",
"secapi_factor_exposures",
"market_calendar"
],
"validation": {
"launchHistoryFloor": "2015-01-01",
"marketCalendarAware": true
}
},
"revision": {
"sourcePublishedAt": "2026-06-09T21:30:00.000Z",
"retrievedAt": "2026-06-09T22:15:00.000Z",
"vintageId": "2026-06-09",
"revisedFrom": null
},
"degradedState": null,
"requestId": "req_2ZK8Q1W9F4M6P7R3",
"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
```
## Give this prompt to your agent
Use SEC API GET /v1/model-portfolios/{portfolioId}/factor-view for a saved model portfolio's factor profile. Preserve `portfolioId`, `label`, `holdings`, `analysis`, `positionViews`, `positionExposures`, `freshness`, `methodology`, `requestId`, and `traceparent`.
## Failure posture
* treat non-2xx responses as contract-aware failures, not free-form errors
* preserve `requestId` and `traceparent` in logs and downstream reports
* if provenance or freshness metadata is present, return it unchanged so trust is not lost in the handoff