predictions

List predictions for one indicator of a currency

Returns every available prediction for the requested currency/indicator pair. Each row is stamped with its original generated_at and full source provenance (real archived vintage vs FXMacroData's own live-generated forecast, never reconstructed with later data). Per-source archive start dates and market-consensus coverage vary by indicator: see https://fxmacrodata.com/documentation/point-in-time-backtesting for the exact earliest date per source and indicator before assuming multi-year depth exists for every series.

Authentication: this endpoint requires an API key on every currency, including USD. Anonymous callers receive 401 api_key_required. A 14-day free trial at https://fxmacrodata.com/subscribe opens the full history on every supported currency.

get/v1/predictions/{currency}/{indicator}

Request

  • Base URL: https://api.fxmacrodata.com
  • URL: https://api.fxmacrodata.com/v1/predictions/{currency}/{indicator}
  • Auth: one of:
    • none
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

currency'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CNH' | 'CNY' | 'DKK' | 'EUR' | 'GBP' | 'HUF' | 'ILS' | 'JPY' | 'KRW' | 'MYR' | 'NGN' | 'NOK' | 'NZD' | 'PEN' | 'SEK' | 'THB' | 'TWD' | 'USD' required
Example:AUD

Required path parameter. Allowed values: AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, HUF, ILS, JPY, KRW, MYR, NGN, NOK, NZD, PEN, SEK, THB, TWD, USD.

indicator'afe_dollar_index' | 'average_hourly_earnings' | 'average_hourly_earnings_mom' | 'balance_on_goods' | 'balance_on_services' | 'bgcr' | 'breakeven_inflation_rate' | 'broad_dollar_index' | 'broad_money' | 'building_approvals' | 'building_permits' | 'business_confidence' | 'capital_account_balance' | 'cb_assets' | 'commodity_price_energy' | 'commodity_price_ex_energy' | 'commodity_price_index' | 'commodity_prices' | 'consumer_confidence' | 'core_inflation' | 'core_inflation_median' | 'core_inflation_mom' | 'core_inflation_trim' | 'core_pce' | 'core_pce_mom' | 'credit_growth' | 'crude_oil_inventories' | 'current_account_balance' | 'dairy_exports' | 'deposit_rates' | 'durable_goods_orders' | 'effr' | 'eme_dollar_index' | 'employment' | 'exports' | 'financial_account_balance' | 'foreign_reserves' | 'full_time_employment' | 'fx_reserves' | 'gdp' | 'gdp_growth_q4_yoy' | 'gold_reserves' | 'gov_bond_10y' | 'gov_bond_15y' | 'gov_bond_1_5m' | 'gov_bond_1m' | 'gov_bond_1y' | 'gov_bond_20y' | 'gov_bond_25y' | 'gov_bond_2m' | 'gov_bond_2y' | 'gov_bond_30y' | 'gov_bond_3m' | 'gov_bond_3y' | 'gov_bond_40y' | 'gov_bond_4m' | 'gov_bond_4y' | 'gov_bond_5y' | 'gov_bond_6m' | 'gov_bond_6y' | 'gov_bond_7y' | 'gov_bond_8y' | 'gov_bond_9y' | 'government_debt' | 'house_price_index' | 'house_prices' | 'household_credit' | 'household_spending' | 'housing_starts' | 'import_prices' | 'imports' | 'industrial_production' | 'inflation' | 'inflation_linked_bond' | 'inflation_mom' | 'initial_jobless_claims' | 'international_assets' | 'international_liabilities' | 'job_openings' | 'm1' | 'm2' | 'm3' | 'nairu' | 'natural_gas_storage' | 'net_foreign_asset_position' | 'non_farm_payrolls' | 'non_farm_payrolls_change' | 'obfr' | 'part_time_employment' | 'participation_rate' | 'pce' | 'pce_mom' | 'policy_rate' | 'policy_rate_midpoint' | 'policy_rate_mlf' | 'policy_rate_mro' | 'policy_rate_target_lower' | 'ppi' | 'primary_income_balance' | 'productivity' | 'real_yield_20y' | 'real_yield_30y' | 'real_yield_5y' | 'real_yield_7y' | 'retail_sales' | 'retail_sales_control_group' | 'retail_sales_ex_autos' | 'retail_sales_ex_autos_and_gas' | 'risk_free_rate' | 'secondary_income_balance' | 'sight_deposits' | 'snb_balance_sheet' | 'sofr_average_180d' | 'sofr_average_30d' | 'sofr_average_90d' | 'sofr_index' | 'terms_of_trade' | 'tgcr' | 'trade_balance' | 'trade_weighted_index' | 'trimmed_mean_inflation' | 'unemployment' | 'wage_price_index' | 'wages' required

Indicator slug

Example:afe_dollar_index

Required path parameter. Indicator slug Allowed values: afe_dollar_index, average_hourly_earnings, average_hourly_earnings_mom, balance_on_goods, balance_on_services, bgcr, breakeven_inflation_rate, broad_dollar_index, broad_money, building_approvals, building_permits, business_confidence, capital_account_balance, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, core_pce_mom, credit_growth, crude_oil_inventories, current_account_balance, dairy_exports, deposit_rates, durable_goods_orders, effr, eme_dollar_index, employment, exports, financial_account_balance, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gold_reserves, gov_bond_10y, gov_bond_15y, gov_bond_1_5m, gov_bond_1m, gov_bond_1y, gov_bond_20y, gov_bond_25y, gov_bond_2m, gov_bond_2y, gov_bond_30y, gov_bond_3m, gov_bond_3y, gov_bond_40y, gov_bond_4m, gov_bond_4y, gov_bond_5y, gov_bond_6m, gov_bond_6y, gov_bond_7y, gov_bond_8y, gov_bond_9y, government_debt, house_price_index, house_prices, household_credit, household_spending, housing_starts, import_prices, imports, industrial_production, inflation, inflation_linked_bond, inflation_mom, initial_jobless_claims, international_assets, international_liabilities, job_openings, m1, m2, m3, nairu, natural_gas_storage, net_foreign_asset_position, non_farm_payrolls, non_farm_payrolls_change, obfr, part_time_employment, participation_rate, pce, pce_mom, policy_rate, policy_rate_midpoint, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, primary_income_balance, productivity, real_yield_20y, real_yield_30y, real_yield_5y, real_yield_7y, retail_sales, retail_sales_control_group, retail_sales_ex_autos, retail_sales_ex_autos_and_gas, risk_free_rate, secondary_income_balance, sight_deposits, snb_balance_sheet, sofr_average_180d, sofr_average_30d, sofr_average_90d, sofr_index, terms_of_trade, tgcr, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.

Query parameters

prediction_class'compiled_consensus' | 'forecaster_survey' | 'expectations_survey' | 'market_implied' | 'model_nowcast' | 'central_bank_projection' | 'institutional_projection' | 'fxmacrodata' nullable

Filter by how the forecast was produced. Prefer this over prediction_type: one class can span several legacy types, which is how forecaster_survey returns both the ECB and Philadelphia Fed Surveys of Professional Forecasters.

Optional query parameter. Filter by how the forecast was produced. Prefer this over prediction_type: one class can span several legacy types, which is how forecaster_survey returns both the ECB and Philadelphia Fed Surveys of Professional Forecasters.

prediction_type'market_consensus' | 'market_prediction' | 'model_nowcast' | 'survey' | 'central_bank_forecast' | 'central_bank_projection' | 'imf_weo' | 'oecd_eo' | 'fxmacrodata' nullable

Optional legacy prediction-type filter, retained unchanged for existing clients. Superseded by prediction_class.

Optional query parameter. Optional legacy prediction-type filter, retained unchanged for existing clients. Superseded by prediction_class.

prediction_sourcestring nullable

Optional source identifier filter.

Optional query parameter. Optional source identifier filter.

official_limitinteger

Maximum rows in official_forecasts (native-period official forecasts and surveys). 0 omits them.

Optional query parameter. Maximum rows in official_forecasts (native-period official forecasts and surveys). 0 omits them.

pre_release_onlyboolean

Return only forecasts with generated_at strictly before the linked announcement_datetime (default: true). FXMacroData only publishes forecasts generated before the announcement, so this flag is informational: setting it to false does not return additional rows.

Optional query parameter. Return only forecasts with generated_at strictly before the linked announcement_datetime (default: true). FXMacroData only publishes forecasts generated before the announcement, so this flag is informational: setting it to false does not return additional rows.

seasonality'sa' | 'nsa' nullable

Optional seasonal adjustment selector, matching /v1/announcements.

Example:sa

Optional query parameter. Optional seasonal adjustment selector, matching /v1/announcements. Allowed values: sa, nsa.

frequency'level' | 'yoy' | 'qoq' | 'mom' nullable

Optional returned change basis selector, matching /v1/announcements.

Example:level

Optional query parameter. Optional returned change basis selector, matching /v1/announcements. Allowed values: level, yoy, qoq, mom.

annualization'not_annualized' | 'saar' nullable

Optional annualization selector, matching /v1/announcements.

Example:not_annualized

Optional query parameter. Optional annualization selector, matching /v1/announcements. Allowed values: not_annualized, saar.

period_aggregation'monthly' | 'quarterly_average' nullable

Optional period aggregation selector, matching /v1/announcements.

Example:monthly

Optional query parameter. Optional period aggregation selector, matching /v1/announcements. Allowed values: monthly, quarterly_average.

basis'real' | 'nominal' nullable

Optional real/nominal selector, matching /v1/announcements.

Example:real

Optional query parameter. Optional real/nominal selector, matching /v1/announcements. Allowed values: real, nominal.

start_datestring nullable

Start date YYYY-MM-DD (period date). Defaults to 180 days before today when omitted.

Optional query parameter. Start date YYYY-MM-DD (period date). Defaults to 180 days before today when omitted.

end_datestring nullable

End date YYYY-MM-DD (period date). Defaults to 90 days ahead when omitted.

Optional query parameter. End date YYYY-MM-DD (period date). Defaults to 90 days ahead when omitted.

limitinteger

Maximum number of prediction groups to return in data[]. Use with offset to page through long histories. Defaults to 20. Maximum 100.

Example:20

Optional query parameter. Maximum number of prediction groups to return in data[]. Use with offset to page through long histories. Defaults to 20. Maximum 100.

offsetinteger

Number of prediction groups to skip from the start of data[]. Use with limit for pagination. Defaults to 0.

Optional query parameter. Number of prediction groups to skip from the start of data[]. Use with limit for pagination. Defaults to 0.

pageinteger nullable

One-based page number. When supplied, it takes precedence over offset.

Example:1

Optional query parameter. One-based page number. When supplied, it takes precedence over offset.

before_datestring nullable

Return groups strictly before this YYYY-MM-DD period date. Use the previous response's next_cursor for bounded pagination.

Optional query parameter. Return groups strictly before this YYYY-MM-DD period date. Use the previous response's next_cursor for bounded pagination.

as_ofstring nullable

Optional query parameter.

event_compatible_onlyboolean

Optional query parameter.

api_keystring

Your Individual or Business API key

Deprecated: legacy query-string API key. Still accepted so existing integrations keep working, but new integrations must send the key in the X-API-Key header (or Authorization: Bearer). A key is required for non-USD, paid-only, or full-history requests. Responses to requests authenticated this way carry a Deprecation header.

Response

Successful Response

as_ofstring nullable
event_compatible_onlyboolean
currencystring required
indicatorstring nullable
selected_series_idstring nullable
supported_optionsobject nullable
prediction_typestring nullable
prediction_classstring nullable
prediction_sourcestring nullable
pre_release_onlyboolean
start_datestring nullable
end_datestring nullable
next_cursorstring nullable

Exclusive before_date cursor for the next page. Prefer this over deep offset pagination to keep reads bounded.

has_moreboolean
countinteger

Number of announcement groups returned in data.

prediction_countinteger

Total number of per-source predictions across all groups.

availabilityobject nullable

Why a filter returned what it returned. classes_with_sources and types_with_sources list what any caller could ever get for this pair; reason explains a requested filter that came back empty. no_source_for_pair means no publisher provides it and no plan adds it.

official_forecastsobject[]

Official forecasts and surveys for this indicator in the publisher's own period and unit (quarterly averages, annual rates, survey horizons), newest publication first, every vintage. Not merged into data because their period basis differs from the monthly announcement; target_period, period_basis and unit say exactly what each number is. Same prediction_class vocabulary as data; filtered by prediction_class, prediction_source, start_date and end_date (on the publication date).

official_forecast_countinteger

Number of rows in official_forecasts.

official_forecast_calendarobject[]

Confirmed official forecast publication times for this currency over the next 366 days. These are publisher releases, separate from the indicator's announcement times.

official_forecasts_truncatedboolean

True when more official forecast vintages exist than the official_limit returned; narrow start_date/end_date or prediction_source to see the rest.

Example response

{
  "data": [
    {
      "announcement_id": "usd_inflation_2026-01-31"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.