API authentication, free access, and rate limits

Free access

What works without an API key

Free access needs no sign-up, no card, and no key, and it does not expire. These requests work keyless:

• USD announcement data — /v1/announcements/usd/{indicator} and /v1/announcements/usd/latest, covering the most recent 90 days. Each release becomes readable 15 minutes after it is published.
• USD announcement change feed — /v1/announcements/changes, on the same 15-minute delay.
• USD release calendar — /v1/calendar/usd.
• Data catalogue — /v1/data_catalogue/{currency}, listing the indicator slugs for every currency.
• USD official press releases — /v1/press-releases/usd.
• USD COT positioning — /v1/cot/usd, covering the most recent 90 days.
• Forecast coverage — /v1/predictions/coverage/{currency}, which lists the forecast sources for each indicator in every currency, without the forecast values.
• Risk sentiment and market sessions — /v1/risk_sentiment and /v1/market_sessions.

Keyless traffic has a fair-use allowance of 100 requests per day per client address, whatever client sends it. Every keyless response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset so you can see the allowance being used.

What needs an API key

• Every currency other than USD.
• Forecast values from /v1/predictions/{currency}/{indicator}, for every currency including USD.
• Real-time USD releases without the 15-minute delay, and USD history older than 90 days.
• FX rates, commodities, rate differentials, curves, SSE streams, and webhooks.

A trial or paid plan unlocks all of it. Compare plans →

Authentication

Send your key in a request header.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fxmacrodata.com/v1/announcements/eur/policy_rate"

import requests

resp = requests.get(
    "https://api.fxmacrodata.com/v1/announcements/eur/policy_rate",
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["data"][0])

Query-string keys are deprecated. The legacy ?api_key=YOUR_API_KEY parameter is still accepted so existing integrations keep working, but new code should use a header: keys placed in URLs end up in server logs, proxy logs, and browser history.

Browser use

Call the API from your server, not the browser.

The API is built for server-side use: backends, scripts, notebooks, and scheduled jobs. It does not send CORS headers to browser origins, so a fetch() from a web page on your own domain is blocked by the browser. Call FXMacroData from your backend, cache the response, and serve your front end from there. That also keeps your API key out of client-side code, where anyone can read it.

Request budgets

Plan limits

Enterprise fair use. Enterprise limits are set in each agreement, which can include a higher monthly allowance and no per-minute, per-hour, or concurrency caps. Fair use means traffic consistent with operating your own products: server-side calls at a refresh cadence your application needs, with responses cached rather than re-requested. It does not cover mirroring the catalogue, bulk historical extraction for resale, reselling access, or passing raw responses through to your own end users as a data feed. If usage looks like one of those, we will contact you to agree terms before applying any limit — we do not throttle Enterprise keys without notice. If you expect to exceed the monthly allowance, contact us and we will raise it in advance.

Release delay

Free access is 15 minutes behind. Keys are real time.

Without an API key, an announcement becomes readable 15 minutes after it is published. This applies to every anonymous announcement surface: /v1/announcements/{currency}/{indicator}, /v1/announcements/{currency}/latest, /v1/announcements/changes, /v1/latest/announcements/*, /v1/recent/announcements/*, GraphQL, and the MCP server. An Individual or Business key removes it everywhere, and adds SSE and webhook delivery, which push a release rather than waiting for your next poll.

A delayed response says so. Every anonymous response carries a freemium_delay object, whether or not anything was actually withheld, so a delayed response is never mistakable for a current one.

"freemium_delay": {
  "applied": true,
  "delay_seconds": 900,
  "cutoff": 1789136100,
  "cutoff_iso": "2026-09-11T13:35:00Z",
  "withheld_count": 1,
  "next_available_at": 1789137000,
  "next_available_at_iso": "2026-09-11T13:50:00Z",
  "message": "Free access is delayed by 15 minutes. 1 release published in the last 15 minutes is withheld from this response. An Individual or Business API key returns them in real time.",
  "subscribe_url": "https://fxmacrodata.com/subscribe"
}

• cutoff is the newest release timestamp an anonymous caller can read. It advances on a five-minute grid, so repeat polls inside one step share a cached response.
• On /v1/announcements/{currency}/latest, an indicator whose newest print is withheld reports the previous print, a withheld marker, and null change fields. The percentage change is withheld with the value because publishing both would give the value back.
• On /v1/announcements/changes, next_cursor stops at the cutoff rather than stepping over a withheld event, so nothing is skipped: the event arrives on a later poll, once it is 15 minutes old.
• Historical rows are unaffected. The delay bounds recency only, and is separate from the 90-day anonymous history window.

Get real-time access →

429 behavior

Use response headers to back off cleanly.

Every metered response, keyed or keyless, carries the IETF RateLimit-* headers alongside the older X-RateLimit-* trio.

On a 429, Retry-After equals RateLimit-Reset, and X-RateLimit-Window names whether the minute, hour, day, month, endpoint, or concurrency budget was the binding constraint.

Responses served from the edge cache (X-FXMD-Edge-Cache: HIT or R2-HIT) carry no RateLimit-* or X-RateLimit-* headers. A cached response is shared between callers, so the quota figures it was fetched with would describe someone else's allowance; the edge does not count per caller, so it omits them rather than guess. An edge hit does not consume your quota. Read your remaining allowance from any response marked MISS or BYPASS.

HTTP/1.1 200 OK
RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 42
RateLimit-Policy: 300;w=60, 5000;w=3600, 1000000;w=2246400

{
  "detail": "Anonymous USD API access is limited to 100 requests per day. Subscribe for an API key and higher limits: https://fxmacrodata.com/subscribe",
  "code": "anonymous_usd_rate_limit_exceeded",
  "error": "anonymous_usd_rate_limit_exceeded"
}

Efficiency

Reduce quota use before adding retries.

• Send Accept-Encoding: gzip on requests. Most HTTP clients negotiate this automatically.
• Use If-None-Match with the latest ETag when polling the same resource.
• Pass ?limit= on history endpoints when you only need recent rows. For a complete range, page with limit=100 and offset as shown in the pagination guide.
• Use /v1/latest/* and /v1/recent/* routes when you only need the newest records.
• Stay below the concurrency cap when polling multiple currencies or indicators in parallel.