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

# Macro Intelligence

> Country-level macro data, release calendars, forecasts, regimes, and agent-ready country reports

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

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

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

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

```bash theme={null}
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/macro/indicators?country=US&indicator=CPIAUCSL&limit=12&response_mode=compact"
```

| Parameter       | Required | Default       | Notes                                                  |
| --------------- | -------: | ------------- | ------------------------------------------------------ |
| `indicator`     |      Yes | --            | Alias: `indicator_key`                                 |
| `country`       |       No | `US`          | ISO country code                                       |
| `limit`         |       No | route default | Max `240`                                              |
| `response_mode` |       No | `standard`    | `compact`, `standard`, `verbose`, or `agent`           |
| `include`       |       No | --            | Comma-separated expansions such as `trust` or `series` |

### 4. Separate Released History From Upcoming Calendar

Released history:

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

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

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

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

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

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

| Field          | Type          | Notes                                                                   |
| -------------- | ------------- | ----------------------------------------------------------------------- |
| `symbols`      | string array  | Adds a lightweight company lens                                         |
| `holdings`     | holding array | Adds portfolio lens using the same holding shape as portfolio endpoints |
| `horizon`      | enum          | `1m`, `3m`, `6m`, `12m`, or `18m`                                       |
| `briefingMode` | enum          | `macro`, `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:

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

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

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

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

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

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

| Ring           | Countries                                | Posture                                                     |
| -------------- | ---------------------------------------- | ----------------------------------------------------------- |
| Launch ring    | `US`, `CN`, `JP`, `TW`, `IL`             | Curated official-source coverage, deepest launch validation |
| Expansion ring | `CA`, `GB`, `EZ`, `KR`, `BR`, `IN`, `SA` | Smaller high-signal packs, explicit source/fallback posture |

For source-level detail, see [Macro Tier-1 Official Sources](/macro-tier1).

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