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:

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

Why the response shape is useful

1. Citable institutional provenance

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

{
  "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:

{
  "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

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:

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.

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):

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.

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.

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