---
title: "Sugra Macro"
description: "Official economic record: central banks, statistical agencies, global trade, and public finance - published series only."
slug: sugra-macro
status: published
published_at: 2026-05-26
author: Arman Obosyan
author_url: https://sugra.systems/about
section: foundation
series_order: 2
primary_keyword: sugra macro api
hero_image: /blog/images/posts/sugra-macro-hero.jpg
hero_alt: "Sugra Macro - Sugra API blog"
og_image: /blog/images/posts/sugra-macro-hero.jpg
tags:
  - macro
  - economy
  - api
---

# Sugra Macro: the official economic record behind one API key

**Series:** Sugra product directions (2 of 7)  
**Audience:** developers integrating the Sugra API over HTTP  
**Live samples verified:** 2026-07-24 against `https://sugra.ai`  
**Auth:** `x-api-key` header on every data call  

Standalone article. You do not need Finance or other directions to use Macro.  
This is not investment advice and not a forecast engine. Macro returns **published official series** only.

---

## Essence

> The official economic record - central banks, statistical agencies, global trade - normalized into one API.

Sugra Macro covers monetary policy, official statistics, international trade, public finance, and the US Treasury market surface. Every upstream is a sovereign institution, intergovernmental body, or academic project. Sources are named openly in `meta.source` (for example `fred`, `bis`, `us_treasury`).

There are no commercial Tier C market vendors in this direction.

---

## What this direction is not

| Not this | Why |
|---|---|
| Forecasts, nowcasts, or consensus estimates | Only published official series |
| Market quotes or 13F books | That is **Sugra Finance** |
| Sanctions / KYB screening | That is **Sugra Entity** |
| News headlines about the Fed | That is **Sugra News** |
| Investment advice | You get the record; you form the view |

---

## Capability map

Portal catalog order of magnitude (2026-07-18):

| Category | Endpoints (approx.) | Coverage |
|---|---|---|
| Central Banks and Monetary | 268 | Fed, FRED, ECB, BIS, BoJ, BoC, SNB, Riksbank, Norges Bank, BCB, and peers |
| Statistical Agencies | 165 | BEA, BLS, Census, Eurostat, ONS, Destatis, INSEE, StatCan, and peers; ILOSTAT labor |
| Global Economy and Trade | 80 | IMF, World Bank, OECD, WTO, UN Comtrade, WITS, Global Trade Alert |
| Public Finance and Government | 66 | US Treasury fiscal, TIC, USAspending, Congress.gov |
| Fixed Income | 19 | Par / GSW / TIPS curves, CUSIP analytics, auctions |
| Macro / Economics panels | composed | `/api/v1/macro/*` catalogs and cross-country indicators |

Family page badges often show **490+** Macro endpoints. Use live OpenAPI for exact counts.

Shared envelope:

```text
{ "data": ..., "meta": { "endpoint", "data_time", "source", ... } }
```

---

## Why the response shape is useful

### 1. Citable institutional provenance

Live FRED CPI sample (2026-07-24, truncated):

```json
{
  "data": {
    "series_id": "CPIAUCSL",
    "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
    "units": "Index 1982-1984=100",
    "frequency": "Monthly",
    "last_updated": "2026-07-14 08:10:40-05",
    "observations": [
      { "date": "2026-06-01", "value": 332.568 },
      { "date": "2026-05-01", "value": 333.979 }
    ]
  },
  "meta": { "source": "fred" }
}
```

Agents should print `meta.source` and observation dates instead of memorized macro numbers.

### 2. Server-side transforms (level to growth)

FRED accepts `units=pc1` (percent change from a year ago). Live real GDP:

```json
{
  "data": {
    "series_id": "GDPC1",
    "transform": { "units": "pc1" },
    "observations": [
      { "date": "2026-01-01", "value": 2.68474 },
      { "date": "2025-10-01", "value": 1.9893 }
    ]
  },
  "meta": { "source": "fred" }
}
```

Growth axis for a regime monitor without local math.

### 3. World policy rates in one call

`GET /api/v1/bis/cb-rates` returned **49** country/area rows live, including US `3.625` (2026-06), Brazil `14.25`, Euro area `2.25`, Japan `1`. History: `/bis/cb-rates/{country}?last_n=`.

### 4. Cross-check primary curves

US Treasury par yield curve (2026-07-23 live): 1M 3.82 through 30Y 5.17; 10Y 4.71, 2Y 4.37. Pair with FRED `T10Y2Y` for the classic spread.

### 5. Discovery catalog

`GET /api/v1/macro/catalog` is a large, fast discovery payload (no upstream round-trip for the catalog itself) with series metadata, transforms, and cache policy.

---

## Developer path

```bash
export SUGRA_API_KEY="YOUR_API_KEY"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fred/series/CPIAUCSL?limit=3"
```

Python:

```python
import os, requests
H = {"x-api-key": os.environ["SUGRA_API_KEY"]}
r = requests.get(
    "https://sugra.ai/api/v1/fred/series/GDPC1",
    headers=H, params={"limit": 2, "units": "pc1"}, timeout=30,
)
r.raise_for_status()
data, meta = r.json()["data"], r.json()["meta"]
```

---

## Use case 1: Macro regime monitor

**Goal.** Three axes: growth, inflation, curve (plus policy cross-check).

**Calls.**

```bash
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fred/series/GDPC1?limit=3&units=pc1"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fred/series/CPIAUCSL?limit=3&units=pc1"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fred/series/UNRATE?limit=3"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fred/series/T10Y2Y?limit=3"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/bis/cb-rates/US?last_n=3"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/fixed-income/treasury/yield-curve"
```

**Client reduce (example thresholds - yours to define):**

```python
summary = {
    "growth": "expansion" if gdp_yoy > 0 else "contraction",
    "inflation": "above target" if cpi_yoy > 2 else "at or below target",
    "curve": "inverted" if t10y2y < 0 else "normal",
    "real_policy": policy_rate - cpi_yoy,
}
```

**Strength.** Multi-institution cross-check (FRED + BIS + Treasury) under one key.  
**Pitfalls.** Release calendars and revisions; BIS monthly lag; do not over-claim precision on real-rate math.

Portal recipe: `macro-regime-monitor.md`.

---

## Use case 2: CPI watch desk

**Goal.** Inflation path for one country.

**Calls.** FRED `CPIAUCSL` with `units=pc1`, or BIS `/api/v1/bis/cpi?country=us&last_n=12`.

**Strength.** Official print with title, units, frequency, `last_updated`.  
**Pitfalls.** Headline vs core series are different IDs - pick deliberately.

---

## Use case 3: Global policy rate map

**Goal.** Who is tight or loose across countries.

**Calls.**

```bash
curl -H "x-api-key: $SUGRA_API_KEY" "https://sugra.ai/api/v1/bis/cb-rates"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/bis/cb-rates/BR?last_n=12"
```

**Strength.** One table instead of N central-bank scrapers.  
**Pitfalls.** Some rows can be historical last-known or `NaN` for discontinued series - filter client-side.

---

## Use case 4: Cross-country indicator panel

**Goal.** Harmonized CPI (or other symbols) across countries.

**Calls.**

```bash
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/macro/catalog"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/macro/indicators?symbol=CPI&country=DE"
```

**Strength.** Panel composition without maintaining separate SDMX clients.  
**Pitfalls.** Not every symbol exists for every country - discover via catalog first.

---

## Use case 5: Yield curve and rates path

**Goal.** Daily curve shape plus classic spreads.

**Calls.** Treasury yield curve + FRED `T10Y2Y`, `DGS10`, `DFF` as needed.

**Strength.** Primary curve points with tenor labels. Live curve date 2026-07-23: upward slope 1M to 20Y/30Y region.  
**Pitfalls.** Holiday gaps; weekend last print.

---

## Use case 6: US fiscal pulse

**Goal.** Debt, auctions, deficit context from Treasury surfaces under Public Finance.

**When.** Research desks and agents that need fiscal context without Bloomberg.

**Strength.** Sovereign source naming.  
**Pitfalls.** Fiscal data cadence differs from daily rates.

---

## Use case 7: Trade and intervention context

**Goal.** Official trade statistics and policy interventions (IMF DOT, Comtrade, Global Trade Alert).

**When.** Trade research, sanctions-adjacent *economic* context (not Entity screening).

**Strength.** Tier S / I naming.  
**Pitfalls.** Trade data lag is large; not a daily news product.

---

## Use case 8: Agent cite-or-die grounding

**Goal.** Replace model-memory macro claims with API observations.

**Pattern.** Fetch series -> return value + date + `meta.source` in the agent reply.

**Strength.** This is Macro's primary product for AI agent builders.  
**Pitfalls.** Always include observation date; never present a stale print as "current" without `data_time`.

---

## Scenarios where Macro alone is enough

- Official inflation / labor / GDP dashboards  
- Global CB policy map  
- US curve monitor  
- Research agents that must cite FRED/BIS/Treasury  
- Teaching notebooks on the official record  

Not enough alone for: equity trading desks (Finance), sanctions (Entity), media tone (News).

---

## Live verification (2026-07-24)

| Call | Result |
|---|---|
| FRED CPI, GDP pc1, UNRATE, T10Y2Y | 200 |
| BIS cb-rates (+ US history), BIS CPI | 200 |
| macro catalog, indicators DE CPI | 200 |
| Treasury yield curve | 200 |

---

## Where to go next

- Portal: Sugra Macro direction + Macro sources  
- Recipe: `macro-regime-monitor`  
- Cookbook: `04_economics_cpi.py`  
- Series: Finance (previous), Entity (next)

| # | Direction | Status |
|---|---|---|
| 1 | Finance | Published |
| 2 | **Macro** | This article |
| 3 | Entity | Next |
| 4-7 | NetAtlas, News, Earth, Research | Upcoming |

---