Skip to main content
SEC API macro data is built to make SEC, factor, and portfolio workflows more useful. It is not a generic macro database. Use it to give agents and investor systems the country context needed for return attribution, portfolio planning, factor interpretation, forward-return modeling, and risk explanation. The fastest workflow is:
  1. Search for an indicator key.
  2. Fetch compact observations or the country high-signal pack.
  3. Check released history and upcoming calendar events.
  4. Add forecasts and the current macro regime.
  5. Use a compact country report when an agent needs one dense rollup.
  6. Check macro status before citing freshness-sensitive conclusions.
  7. Use scenario and sensitivity endpoints when macro needs to connect to factors or portfolios.
All endpoints return requestId and traceparent. Preserve freshness, provenance, methodology, source-rights, and degraded-state fields when they are present.

​
Workflow Quickstart

​
1. Search Indicators

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/search?q=inflation&country=US&limit=10"
Use the returned indicatorKey in later calls. For example, US CPI is available as CPIAUCSL.

​
2. Fetch A Compact Country Pack

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/high-signal-pack?country=US"
/v1/macro/high-signal-pack defaults to country=US and response_mode=compact. The compact shape is designed for agents: bounded series summaries, latest value, upcoming release, forecast, regime, and source posture. Expand only when needed: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/high-signal-pack?country=US&response_mode=standard&include=series,trust"

​
3. Fetch Observations

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/indicators?country=US&indicator=CPIAUCSL&limit=12&response_mode=compact"
ParameterRequiredDefaultNotes
indicatorYes—Alias: indicator_key
countryNoUSISO country code
limitNoroute defaultMax 240
response_modeNostandardcompact, standard, verbose, or agent
includeNo—Comma-separated expansions such as trust or series

​
4. Separate Released History From Upcoming Calendar

Released history: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/releases?country=US&indicator=CPIAUCSL&status=released&limit=10"
Upcoming scheduled releases: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/calendar?country=US&indicator=CPIAUCSL&days=45&limit=12&response_mode=compact"
/v1/macro/calendar returns future scheduled releases only. Past rows belong in /v1/macro/releases?status=released.

​
5. Add Forecasts And Regime

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/forecasts?country=US&indicator=CPIAUCSL&horizons=3&response_mode=compact"

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/regimes?country=US&lookback=18m&response_mode=compact"
Country-wide forecast calls default to compact because full forecast payloads can be large.

​
6. Check Macro Status

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/status?country=US&response_mode=compact"
/v1/macro/status is artifact-backed when runtime validation artifacts are packaged with the API. If those artifacts are missing or unusable, the route returns an explicit degraded runtime_registry_fallback response instead of probing vendors live. Use it when an agent needs to decide whether macro output is ready, degraded, stale, or unsupported. The compact response includes country status, source posture, alerts, freshness age, statusSource, artifactGeneratedAt, computedAt, and methodology. Agents should treat statusSource: "runtime_registry_fallback" as a caution flag: cite the degraded status, avoid freshness-sensitive claims, and retry later or ask for confirmation from a human teammate. Use response_mode=verbose or view=full only when you need indicator-level rows.

​
7. Use Country Report For A Dense Investment Briefing

curl -X POST \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"country":"US","lookback":"6m","symbols":["AAPL","NVDA"],"briefingMode":"company"}' \
  "https://api.secapi.ai/v1/intelligence/country-report?response_mode=compact"
Use country reports when an agent needs one compact answer containing indicators, releases, forecasts, regime, likely drivers, freshness, and an investor-shaped briefing block. The briefing block includes:
  • topLine
  • regime
  • keyDrivers
  • watchItems
  • investmentImplications
  • dataQuality
Optional request fields:
FieldTypeNotes
symbolsstring arrayAdds a lightweight company lens
holdingsholding arrayAdds portfolio lens using the same holding shape as portfolio endpoints
horizonenum1m, 3m, 6m, 12m, or 18m
briefingModeenummacro, portfolio, or company
Use full mode only when a human or downstream service needs the complete nested payload.

​
8. Connect Macro To Portfolio And Factor Workflows

List supported stress scenarios: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/portfolio/stress-test/scenarios?country=US&response_mode=compact"
Run a stress test and inspect contributions: 
curl -X POST \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"country":"US","scenarioKey":"higher_for_longer","holdings":[{"symbol":"AAPL","weight":0.6},{"symbol":"MSFT","weight":0.4}]}' \
  "https://api.secapi.ai/v1/portfolio/stress-test?response_mode=compact"
Ask which factors are most sensitive to a macro scenario: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/factors/macro-sensitivity?country=US&scenario_key=higher_for_longer&keys=VALUE,MOMENTUM,QUALITY&response_mode=compact"
/v1/factors/macro-sensitivity is labeled macro_factor_sensitivity_v1_heuristic. It combines scenario shock maps with current macro-regime factor impacts. It is explainable and fast; it is not a point-in-time empirical regression.

​
9. One-Call Country Overview

When an agent wants the whole country picture in a single request — headline indicators with latest/previous/change/direction and next release, the current regime, upcoming releases, and the sovereign credit rating — use the overview endpoint: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/overview?country=US"
/v1/macro/overview defaults to country=US. It is the fastest way to orient on an economy before drilling into indicators, releases, or forecasts.

​
10. Bulk Observation Export

For research or backfill, pull a filterable page of raw observations across countries and indicators: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/all?country=US&indicator_type=inflation&limit=250"
/v1/macro/all is cursor-paginated (follow nextCursor) and accepts country (single or comma-separated), indicator_type, indicator, frequency, date_from, date_to, and limit (max 1000). Pass format=csv for an attachment; oversized exports are materialized asynchronously and returned as an export job whose signed download URL arrives via the export.completed webhook event.

​
11. Company Macro Exposure

Cross a single company’s geographic revenue segments with the country macro plane to get revenue-weighted macro sensitivities: 
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/companies/macro-exposure?ticker=AAPL"
Either ticker (alias symbol) or cik is required. The response carries per-indicator beta, direction, confidence, and a coverage percentage that degrades gracefully when revenue segments are unavailable. Use period=quarterly to source the geographic segments from the latest quarterly rather than annual reporting, and country to set the domestic macro plane used for unmapped revenue (defaults to US).

​
Supported Country Coverage

RingCountriesPosture
Launch ringUS, CN, JP, TW, ILCurated official-source coverage, deepest launch validation
Expansion ringCA, GB, EZ, KR, BR, IN, SASmaller high-signal packs, explicit source/fallback posture
For source-level detail, see Macro Tier-1 Official Sources.

​
MCP Tools

Hosted MCP exposes the same workflow for agents:
  • macro.search
  • macro.indicators
  • macro.high_signal_pack
  • macro.releases
  • macro.calendar
  • macro.forecasts
  • macro.regimes
  • macro.status
  • macro.credit_ratings
  • macro.country_report
  • macro.investment_briefing
  • portfolio.stress_scenarios
  • factors.macro_sensitivity
MCP macro tools default to compact response shapes where payload size matters. For large tools such as macro.investment_briefing, set params.content_mode: "minimal" on tools/call so the agent receives full structuredContent without a duplicate text payload. Ask for response_mode: "standard" or include ["series", "trust"] only when the agent needs full nested data.

​
Failure Posture

  • Treat non-2xx responses as contract-aware failures, not free-form errors.
  • Search first when an indicator key is unknown.
  • Preserve requestId and traceparent in downstream artifacts.
  • Cite freshness and source posture when macro data informs an investment claim.