---
title: "List predictions for one indicator of a currency"
method: GET
path: "/v1/predictions/{currency}/{indicator}"
tags: ["predictions"]
---

# List predictions for one indicator of a 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

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.

## 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
- `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

## 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.
- `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`.
- `prediction_source` string, nullable: Optional source identifier filter.
- `official_limit` integer: Maximum rows in ``official_forecasts`` (native-period official forecasts and surveys). 0 omits them.
- `pre_release_only` boolean: 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.
- `frequency` 'level' | 'yoy' | 'qoq' | 'mom', nullable: Optional returned change basis selector, matching /v1/announcements.
- `annualization` 'not_annualized' | 'saar', nullable: Optional annualization selector, matching /v1/announcements.
- `period_aggregation` 'monthly' | 'quarterly_average', nullable: Optional period aggregation selector, matching /v1/announcements.
- `basis` 'real' | 'nominal', nullable: Optional real/nominal selector, matching /v1/announcements.
- `start_date` string, nullable: Start date YYYY-MM-DD (period date). Defaults to 180 days before today when omitted.
- `end_date` string, nullable: End date YYYY-MM-DD (period date). Defaults to 90 days ahead when omitted.
- `limit` integer: Maximum number of prediction groups to return in `data[]`. Use with `offset` to page through long histories. Defaults to 20. Maximum 100.
- `offset` integer: Number of prediction groups to skip from the start of `data[]`. Use with `limit` for pagination. Defaults to 0.
- `page` integer, nullable: One-based page number. When supplied, it takes precedence over offset.
- `before_date` string, nullable: Return groups strictly before this YYYY-MM-DD period date. Use the previous response's `next_cursor` for bounded pagination.
- `as_of` string, nullable
- `event_compatible_only` boolean
- `api_key` string: Your Individual or Business API key

## Response `200`

Successful Response

- PredictionsResponse
  - `as_of` string, nullable
  - `event_compatible_only` boolean
  - `currency` string, required
  - `indicator` string, nullable
  - `filters` object: The series-variant filters this request was resolved with. A null means the caller did not constrain that dimension.
    - `seasonality` string, nullable
    - `basis` string, nullable
    - `annualization` string, nullable
    - `period_aggregation` string, nullable
    - `frequency` string, nullable
    - `revisions` string, nullable
  - `selected_series_id` string, nullable
  - `selected_series` object: The concrete series variant chosen for this response.
    - `series_id` string, nullable
    - `label` string, nullable
    - `source_series_id` string, nullable
    - `seasonality` string, nullable
    - `basis` string, nullable
    - `annualization` string, nullable
    - `period_aggregation` string, nullable
    - `frequency` string, nullable
    - `revisions` string, nullable
  - `supported_options` object, nullable
  - `prediction_type` string, nullable
  - `prediction_class` string, nullable
  - `prediction_source` string, nullable
  - `pre_release_only` boolean
  - `start_date` string, nullable
  - `end_date` string, nullable
  - `next_cursor` string, nullable: Exclusive `before_date` cursor for the next page. Prefer this over deep offset pagination to keep reads bounded.
  - `has_more` boolean
  - `count` integer: Number of announcement groups returned in ``data``.
  - `prediction_count` integer: Total number of per-source predictions across all groups.
  - `data_quality` DataQuality, required
    - `source_freshness` string, nullable
    - `source_monitoring_complete` boolean, nullable
    - `known_source_gap` boolean, nullable
    - `source_checked_at` integer, nullable
    - `source_check_expires_at` integer, nullable
    - `latest_published_period` string, nullable
    - `source_permission_status` string, nullable
    - `commodity_coverage` CommodityCoverage
      - `scope` string, required
      - `requested_start` string, nullable
      - `requested_end` string, nullable
      - `available_start` string, nullable
      - `available_end` string, nullable
      - `input_row_count` integer, required
      - `row_count` integer, required
      - `distinct_date_count` integer, required
      - `duplicate_date_row_count` integer, required
      - `excluded_weekend_row_count` integer, required
      - `invalid_date_row_count` integer, required
      - `expected_weekday_label_count` integer, required
      - `missing_weekday_label_count` integer, required
      - `largest_missing_weekday_run` integer, required
      - `largest_calendar_gap_days` integer, required
      - `missing_weekday_ranges` CommodityMissingWeekdayRange[], required
        - `start_date` string, required
        - `end_date` string, required
        - `weekday_count` integer, required
      - `longest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `latest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `sparse_history` boolean, required
      - `coverage_basis` string, required
      - `continuous_coverage_verified` boolean
      - `reference_only` boolean
      - `executable_quotes` boolean
      - `provenance_version` integer, required
      - `repaired_excluded_weekend_row_count` integer
      - `repaired_invalid_date_row_count` integer
    - `stored_history_coverage` CommodityCoverage
      - `scope` string, required
      - `requested_start` string, nullable
      - `requested_end` string, nullable
      - `available_start` string, nullable
      - `available_end` string, nullable
      - `input_row_count` integer, required
      - `row_count` integer, required
      - `distinct_date_count` integer, required
      - `duplicate_date_row_count` integer, required
      - `excluded_weekend_row_count` integer, required
      - `invalid_date_row_count` integer, required
      - `expected_weekday_label_count` integer, required
      - `missing_weekday_label_count` integer, required
      - `largest_missing_weekday_run` integer, required
      - `largest_calendar_gap_days` integer, required
      - `missing_weekday_ranges` CommodityMissingWeekdayRange[], required
        - `start_date` string, required
        - `end_date` string, required
        - `weekday_count` integer, required
      - `longest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `latest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `sparse_history` boolean, required
      - `coverage_basis` string, required
      - `continuous_coverage_verified` boolean
      - `reference_only` boolean
      - `executable_quotes` boolean
      - `provenance_version` integer, required
      - `repaired_excluded_weekend_row_count` integer
      - `repaired_invalid_date_row_count` integer
    - `point_in_time_basis` string, nullable
    - `is_official` boolean, required
    - `is_proxy` boolean, required
    - `is_fallback` boolean, required
    - `is_stale` boolean, required
    - `has_announcement_datetime` boolean, required
    - `point_in_time_safe` boolean, required: Whether the returned values have verified availability and vintage evidence; estimated release times do not qualify.
    - `unverified_vintage_count` integer
    - `unknown_publication_time_count` integer
    - `latest_available_date` string, nullable
    - `last_updated` string, nullable
    - `data_lag_days` integer, nullable
    - `source_name` string, nullable
    - `source_type` 'official' | 'public' | 'fallback' | 'derived', required
    - `is_derived` boolean
    - `row_count` integer
    - `announcement_datetime_count` integer
    - `missing_announcement_datetime_count` integer
    - `has_assumed_release_times` boolean: True when at least one row in the quality scope carries a publication timestamp derived from the publication lag measured on that series' own confirmed releases, because no official release calendar reaches the period.
    - `assumed_release_time_count` integer: Number of rows in the quality scope whose publication timestamp was derived rather than captured. Compare against row_count to size the derived portion of the requested window.
    - `bounded_release_time_count` integer: Legacy rows carrying an upper-bound estimate flag; this does not certify replay safety.
    - `unbounded_release_time_count` integer: Assumed timestamps without proven availability bounds.
    - `quality_scope` string
    - `stale_after_days` integer, nullable
    - `requested_window_has_data` boolean, nullable
    - `requested_window_latest_date` string, nullable
    - `requested_window_includes_latest_available` boolean, nullable
    - `page_includes_latest_available` boolean, nullable
    - `returned_latest_available_before_window` boolean, nullable
    - `staleness_days` integer, nullable
    - `reason` string, nullable
    - `datetime_field` string, nullable
    - `datetime_precision` string, nullable
    - `datetime_semantics` string, nullable
    - `source_legs` object[], nullable
    - `historical_point_in_time` PointInTimeCompleteness: Coverage of source-confirmed publication timestamps for a dataset.
      - `row_count` integer, required
      - `announcement_datetime_count` integer, required
      - `missing_announcement_datetime_count` integer, required
      - `assumed_release_time_count` integer
      - `bounded_release_time_count` integer
      - `unbounded_release_time_count` integer
      - `unverified_vintage_count` integer
      - `unknown_publication_time_count` integer
      - `point_in_time_safe` boolean, required
  - `availability` object, 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_forecasts` object[]: 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_count` integer: Number of rows in ``official_forecasts``.
  - `official_forecast_calendar` object[]: 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_truncated` boolean: True when more official forecast vintages exist than the ``official_limit`` returned; narrow ``start_date``/``end_date`` or ``prediction_source`` to see the rest.
  - `data` AnnouncementPredictions[], required
    - `announcement_id` string, required: Stable identifier of the announcement these predictions target, in the form ``{currency}_{indicator}_{date}``.
    - `observation_id` string, nullable: Variant-safe identifier for the selected series observation. Use this with `selected_series_id` when query selectors choose a non-default series.
    - `selected_series_id` string, nullable: Stable identifier of the selected announcement series.
    - `currency` string, required
    - `indicator` string, required
    - `date` string, required: Reference period date of the forecast, ``YYYY-MM-DD``.
    - `announcement_datetime` integer, required: Release timestamp of the forecasted announcement, Unix epoch seconds (UTC).
    - `announcement_datetime_local` string, nullable: ISO 8601 release time with timezone offset, rendered in the currency's market timezone.
    - `announcement_timing` 'past' | 'future', nullable: Whether the forecasted announcement is still upcoming (`future`) or already released (`past`).
    - `predictions` PredictionItem[]: List of forecasts for this announcement, one entry per prediction source. Sorted by ``prediction_source`` for deterministic output.
      - `predicted_value` number, required
      - `event_compatible` boolean
      - `event_compatibility_reason` string, nullable
      - `source_url` string, nullable
      - `target_period` string, nullable
      - `period_basis` string, nullable
      - `unit` string, nullable
      - `statistic` string, nullable
      - `publication_date` string, nullable
      - `publication_datetime` string, nullable
      - `publication_precision` string, nullable
      - `forecast_observation_id` string, nullable
      - `seasonal_adjustment` string, nullable
      - `geography` string, nullable
      - `announcement_mapping_verified` boolean
      - `prediction_class` string, nullable: How the forecast was produced, and the field to filter on. One of ``compiled_consensus`` (a publisher's compilation of independent forecasters), ``forecaster_survey`` (an official survey of forecasters or market participants), ``expectations_survey`` (households or businesses), ``market_implied`` (derived from traded prices), ``model_nowcast`` (a published statistical model), ``central_bank_projection`` (the central bank's own projection), ``institutional_projection`` (IMF, OECD), or ``fxmacrodata`` (an FXMacroData estimate, never a market consensus).
      - `prediction_class_label` string, nullable: Human-readable name for ``prediction_class``, for display. Filter on ``prediction_class``, not on this.
      - `prediction_type` string, nullable: Original per-source category, retained unchanged for backward compatibility: ``market_consensus``, ``market_prediction``, ``model_nowcast``, ``survey``, ``central_bank_forecast``, ``central_bank_projection``, ``imf_weo``, ``oecd_eo`` or ``fxmacrodata``. These slugs split identical instruments (the ECB and Philadelphia Fed Surveys of Professional Forecasters landed in different values) and two of them name a publisher rather than a category. Prefer ``prediction_class``.
      - `prediction_source` string, nullable: Stable source identifier slug (e.g. ``philly_fed_spf``, ``cleveland_fed_nowcast``, ``fomc_sep``, ``atlanta_fed_gdpnow``, ``ny_fed_sme``, ``ecb_spf``, ``imf_weo``, ``rbnz_mps``, ``fxmacrodata_blended``). Use this value when filtering via the ``prediction_source`` query parameter.
      - `prediction_source_label` string, nullable: Human-readable name for ``prediction_source`` (e.g. "RBA Statement on Monetary Policy (Table J1)", "Philadelphia Fed Survey of Professional Forecasters", "IMF World Economic Outlook"). Suitable for display in UI surfaces; use ``prediction_source`` for filtering and joins.
      - `generated_at` integer, nullable: Unix epoch seconds (UTC) for the prediction's known-at marker. Inspect `provenance.generated_at_basis` and `provenance.generated_at_precision`: publisher archives may provide a date that FXMacroData normalizes to a documented source-local publication time rather than an original intraday timestamp.
      - `provenance` PredictionProvenance: Documented origin and timestamp semantics for a forecast value.
        - `value_origin` string, required: Whether the value is a publisher historical vintage or an FXMacroData model output.
        - `capture_mode` string, required: Whether FXMacroData recorded the value when it was published or later imported it from the publisher's official archive.
        - `archived_in_real_time_by_fxmacrodata` boolean, required: True only when FXMacroData captured the prediction at the time it was generated or published.
        - `generated_at_basis` string, required: The source fact used to construct `generated_at`.
        - `generated_at_precision` string, required: Precision of the underlying source timestamp. `date` means an official source date was normalized to a documented source-local time.
        - `reconstructed_with_later_data` boolean, required: Whether the prediction value was recomputed using later data or a newer model version.
        - `vintage_selection` string, nullable: Which publisher or model vintages are retained in this feed.
      - `is_pre_release` boolean, nullable: Whether `generated_at` is strictly earlier than the linked `announcement_datetime`. Null when the source did not provide a generation timestamp.
      - `confidence` number, nullable: Confidence score in ``[0.0, 1.0]`` indicating how strong this prediction is. ``1.0`` is maximally confident, ``0.0`` is no confidence. When the source did not record an explicit value, a per-source default is returned (central-bank publications and official surveys score higher than the FXMacroData blended forecast). Use this to weight or filter predictions in client applications.
      - `prediction_reason` string, nullable: Short human-readable explanation of how this prediction was derived. Currently populated for FXMacroData-generated predictions (``prediction_source=fxmacrodata_blended``); it summarises the persistence anchor, momentum/trend extrapolation, cross-indicator pressure, and any external forecast that was blended in. Other prediction sources may omit this field.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api.md) · [All operations](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api/revisions/fadaa543b154?raw)