Backtest macro events without look-ahead bias

Check pre-release forecasts at your decision cutoff

Query the predictions endpoint with pre_release_only=true (the default), as_of, and event_compatible_only=true for event studies. Inspect provenance and data_quality: an official publisher archive can preserve a genuine historical forecast value even when FXMacroData imported it later, and its source may provide only a date rather than an original intraday timestamp. Empty eligible history is a coverage limit to preserve in your results.

GET https://api.fxmacrodata.com/v1/predictions/usd/inflation
    ?pre_release_only=true
    &as_of=2026-08-31T12:00:00Z
    &event_compatible_only=true
    &start_date=2013-08-01
    &end_date=2026-08-31
    &limit=100
X-API-Key: YOUR_API_KEY

Every field a backtest join needs

How the historical forecast values were obtained

FOMC SEP and New York Fed SME rows likewise come from official publisher archives with date-based known-at markers. Read predictions[].provenance on each response. If that object is absent, the source's capture semantics have not yet been audited for this public contract and should not be assumed.

What pre-release history actually exists (USD)

History depends on the publisher archive and the vintages retained by FXMacroData. Use this source overview alongside the coverage matrix, then check the eligible rows for your own cutoff:

There is no separate hidden market_consensus feed for monthly US CPI or NFP on any paid plan. Plan access changes the permitted history window and currency coverage; it does not add prediction sources that are absent from the stored series.

FXMacroData blended forecasts are available where a stored eligible forecast exists. A scheduled announcement does not guarantee a forecast. For non-USD coverage, see the full source-labelled coverage matrix.

Pulling complete history at a decision cutoff

Pass explicit period dates and an as_of decision time. The example downloads all eligible pages for one cutoff, using before_date for forecasts and pagination.next_offset for announcements. It preserves source-unit announcement values with value_mode=source and series_mode=raw. Repeat cutoff selection for each decision in your study; start_date and end_date alone do not protect against later revisions.

import requests

BASE = "https://api.fxmacrodata.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
COMMON = {"start_date": "2013-08-01", "end_date": "2026-08-31",
          "as_of": "2026-08-31T12:00:00Z", "limit": 100}

preds, before_date = [], None
while True:
    params = {**COMMON, "pre_release_only": "true",
              "event_compatible_only": "true"}
    if before_date:
        params["before_date"] = before_date
    response = requests.get(
        f"{BASE}/predictions/usd/inflation", headers=HEADERS, params=params,
        timeout=30,
    )
    response.raise_for_status()
    page = response.json()
    if page["data"] and not page["data_quality"]["point_in_time_safe"]:
        raise ValueError("Forecast availability is not verified for this cutoff")
    preds.extend(page["data"])
    if not page["has_more"]:
        break
    before_date = page["next_cursor"]

actuals, offset, version = [], 0, None
while True:
    params = {**COMMON, "revisions": "latest", "availability": "public",
              "value_mode": "source", "series_mode": "raw", "offset": offset}
    if version:
        params["dataset_version"] = version
    response = requests.get(
        f"{BASE}/announcements/usd/inflation",
        headers=HEADERS,
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    page = response.json()
    version = page["dataset_version"]
    if (page.get("value_mode") != "source"
            or page.get("value_metadata", {}).get("normalization_applied") is not False):
        raise ValueError("Source-unit values were not confirmed")
    if page["data"] and not page["data_quality"]["point_in_time_safe"]:
        raise ValueError("Value-vintage availability is not verified for this cutoff")
    actuals.extend(page["data"])
    pagination = page["pagination"]
    if not pagination["has_more"]:
        break
    offset = pagination["next_offset"]

inputs_by_id = {row["announcement_id"]: row for row in actuals}

An empty result means there are no eligible observations for these settings. dataset_version detects changes between announcement pages; a version conflict requires restarting the download. It is a content fingerprint, not an immutable archive. Retain your downloaded forecast and announcement responses, request settings, and hashes to preserve the evidence used in the study.

These are inputs known at the chosen cutoff. To measure an announcement surprise, separately select an evidenced first-release actual and a compatible pre-release forecast, then verify their units and target period. A latest revised actual must not silently stand in for a first print. See the response field reference for the evidence fields.

Use the same series selectors on both endpoints only when the predictions response advertises that variant in supported_options. CPI supports matching m/m nowcasts. USD NFP does not: the announcement returns the employment level as val and the official jobs gain or loss as change, while the current predictions endpoint forecasts only the level and therefore advertises frequency=level.