---
title: "Get macroeconomic indicator data"
method: GET
path: "/v1/announcements/{currency}/{indicator}"
tags: ["announcements"]
---

# Get macroeconomic indicator data

`GET /v1/announcements/{currency}/{indicator}`

## Request

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

Fetches historical data for a given macroeconomic indicator of a currency.

**Authentication & limits:**
- USD data is publicly accessible without an API key, but anonymous callers are limited to the most recent 90 days. Requests for an earlier `start_date` are clamped to that 90-day window, and the response then carries a `freemium_window` object naming the cutoff so a shortened history is distinguishable from a short series.
- Anonymous USD data is also delayed by 15 minutes. A release is served once it is 15 minutes old; until then it is withheld, and `latest_available_date` reports the newest observation the caller can actually read. Every anonymous response carries a `freemium_delay` object naming the cutoff, the number of withheld releases and when the next one becomes available. An API key removes the delay.
- All other currencies require an Individual or Business API key supplied via `?api_key=<key>` or the `X-API-Key` header.
- Authenticated callers (any valid API key) receive the full requested history for every supported currency, including USD.

**Path Parameters:**
- `currency`: The 3-letter currency code (USD, AUD, EUR, GBP, CHF).
- `indicator`: The indicator name (e.g., inflation, unemployment).

**Query Parameters:**
- `start_date`: Optional. Start date in YYYY-MM-DD format. When omitted by authenticated callers, the endpoint pages through the full available history. Anonymous USD requests are capped to the freemium window.
- `end_date`: Optional. End date in YYYY-MM-DD format. Defaults to today.

- `limit`: Optional page size. Defaults to 20.
- `page`: Optional one-based page number. When provided, it takes precedence over `offset`.
- `offset`: Optional zero-based row offset for offset-based pagination.

- `series_mode`: Optional. `raw` (default) selects the direct underlying indicator series; `canonical` applies configured remaps.
- `value_mode`: `normalized` (default) returns presentation-ready values. `source` requires `series_mode=raw` and returns values and revision values as published by the source, without normalization, derived changes, companion fills or carry-forward. Use source mode for historical research. The response declares `value_mode` and `value_metadata.source_unit`; an unknown source unit is null.

**Empty windows:**
- A valid series with no observations inside the requested window returns `200` with `data: []`, `requested_window_has_data: false`, and a `no_data` object carrying `error_code`, `latest_available_date`, `recommended_start_date` and `available_observation_count`. This is a successful query, not an error, and should not be retried; widen the window instead.
- Anonymous USD callers see this whenever a quarterly or annual series' latest observation predates the 90-day freemium window; `no_data.freemium_clamped` marks that case.
- `404` on this endpoint means the currency or indicator slug is not published. Use `/v1/data_catalogue/{currency}` to list valid slugs.

**Response fields:**
- `remap`: Metadata about the canonical remap rule application (`applied`, `rule_id`, segments, and transform mode).
- `has_official_forecast`: Whether the relevant central bank or statistics agency publishes a preliminary, flash, or advance estimate of this indicator before the main/final data release.
- `earliest_available_date` / `latest_available_date`: The full coverage span available in the response window before any pagination is applied.
- `pagination`: Page metadata for the returned `data[]` slice (`limit`, `offset`, `returned_count`, `total_count`, `has_more`, `next_offset`).
- `data[].announcement_id`: Stable identifier for this unique announcement, in the form `{currency}_{indicator}_{date}` (lowercase, e.g. `usd_inflation_2026-01-31`). Use this to join predictions from `/v1/predictions/{currency}/{indicator}` and revision history back to the underlying observation.
- `data[].announcement_datetime`: Release timestamp as Unix epoch seconds (UTC).
- `data[].announcement_datetime_local`: ISO 8601 release time with offset, rendered in the source agency's local timezone (e.g. USD → America/New_York, AUD → Australia/Sydney).
- `data[].official_planned_release_datetime`: Official planned release timestamp from the publisher's release calendar, as Unix epoch seconds (UTC). Present when the release was captured against a pre-announced official release time.
- `data[].official_actual_release_datetime`: Official release timestamp on the source row, as Unix epoch seconds (UTC). This is normally the same as `announcement_datetime` unless the source exposes a separate publication timestamp.
- `data[].collected_at_ns` / `data[].collected_at_iso`: Exact time FXMacroData first captured this row from the official source.
- `data[].release_timing`: `scheduled_at` is the official schedule. `published_at` equals `published_by`, the observed upper publication bound, not an exact publisher timestamp. `published_after` is the proven lower bound. `picked_up_at` is accepted capture; `available_at` is store commit, not client receipt. `source_pickup_latency_min_ms` / `source_pickup_latency_max_ms` measure publication-to-capture bounds; `latency_ms` and `pickup_ms_*` end at store commit. `publication_delay_ms` is a schedule-to-observed-bound diagnostic. Missing measurements remain null. The 1000ms `source_pickup_slo_ms` is a classification threshold, not a measured latency or guarantee. An unverified publication clock stays unverified.
- `data[].ingestion_latency_ms` / `ingestion_latency_reference`: Deprecated optional diagnostics retained when stored. They measure collection against the original named schedule or actual-release reference, and are never recomputed from the new timing fields. See /documentation/deprecation-policy#legacy-announcement-latency.
- `data[].publication_time_status`: what `announcement_datetime` is evidence of - `confirmed` (the publisher's own timestamp), `unverified` (a real timestamp whose origin the row does not prove; with `publication_time_basis=official_schedule` it is the publisher's scheduled release instant that the value was captured against), `assumed_historical` (derived from measured lag, pre-launch rows only) or `unknown` (no time; the row is served on its period date). A schedule instant is never promoted to `confirmed`.
- `fields=compact`: trims each row to `date`, `val`, `previous_value`, `change_from_previous`, `announcement_datetime`, `announcement_datetime_local` and `publication_time_status`, with `revisions[]` folded into `revisions_summary`. The envelope, pagination and `dataset_version` are the same as the full view.
- `source_series_name`: The actual underlying source series used for this standardized indicator.
- `value_name`: The actual series name used for the returned `val`. For `policy_rate`, this is the canonical policy-series label chosen by the platform (for example, ECB Deposit Facility Rate or Federal Funds Target Range Upper Bound).
- `source_local_name`: Official local-language series label when available.
- `is_proxy`: True when the standardized indicator is populated using a documented proxy rather than a directly named national headline series.
- `proxy_note`: Short explanation of the proxy choice when `is_proxy=true`.
- `policy_role`: For `policy_rate`, the role of the canonical rate inside its official rate family (for example `primary` or `target_upper`).
- `policy_structure`: For `policy_rate`, the policy-regime structure such as `single_primary`, `target_range`, `primary_plus_corridor`, or `non_rate_regime`.
- `comparison_compatible`: For `policy_rate`, whether the returned `val` can be honestly used in cross-country policy-rate comparisons.
- `policy_family`: Optional top-level metadata listing sibling policy-rate indicators in the same official family.
- `data[].predicted_value` *(deprecated — use `/v1/predictions/{currency}/{indicator}` instead)*: Market or professional-forecaster expectation for this indicator reading, in the same units as `val`. Present only where a prediction source is available.
- `data[].prediction_type` *(deprecated — use `/v1/predictions/{currency}/{indicator}` instead)*: Legacy per-source category. See `prediction_class` on `/v1/predictions` for the consolidated axis: `market_consensus` covers both compiled consensus and forecaster surveys, and `market_prediction` is market-implied, not a survey.
- `data[].prediction_source` *(deprecated — use `/v1/predictions/{currency}/{indicator}` instead)*: Stable identifier for the prediction source (e.g. `ecb_spf` for the ECB Survey of Professional Forecasters). Null when `predicted_value` is absent.

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

## Query parameters

- `start_date` string: Start date YYYY-MM-DD
- `end_date` string: End date YYYY-MM-DD
- `series_mode` string: Optional series rendering mode. `canonical` applies configured remap rules (for continuity across methodology transitions). `raw` returns the direct indicator series without remapping.
- `limit` integer: Maximum number of rows to return in `data[]`. Rows are ordered most-recent-first, so `limit=10` returns the 10 most recent observations within the requested window. Use together with `offset` to page through long histories. Defaults to 20. Maximum 100.
- `offset` integer: Number of rows to skip from the start of `data[]` (after most-recent-first ordering). Use with `limit` for pagination. Defaults to 0.
- `page` integer, nullable: One-based page number for callers that prefer page-based pagination. When supplied, `offset` is derived as `(page - 1) * limit`.
- `seasonality` 'sa' | 'nsa', nullable: Optional seasonal adjustment selector. Supported public values are `sa` and `nsa`; check `supported_options.seasonality` in the response/catalogue for values available on this endpoint.
- `frequency` 'level' | 'yoy' | 'qoq' | 'mom', nullable: Optional returned change basis. Supported public values are `level`, `yoy`, `qoq`, and `mom`; check `supported_options.frequency` for values available on this endpoint.
- `annualization` 'not_annualized' | 'saar', nullable: Optional annualization selector. Supported public values are `not_annualized` and `saar`; check `supported_options.annualization` for values available on this endpoint.
- `period_aggregation` 'monthly' | 'quarterly_average', nullable: Optional period-aggregation selector. Supported public values are `monthly` and `quarterly_average`; check `supported_options.period_aggregation` for values available on this endpoint.
- `revisions` 'latest' | 'first' | 'final' | 'all', nullable: Optional revision view. Supported public values are `latest`, `first`, `final`, and `all`; unsupported views return `unsupported_series_option` with supported values.
- `basis` 'real' | 'nominal', nullable: Optional real/nominal selector. Supported public values are `real` and `nominal`; only endpoints with known basis metadata accept it.
- `official_only` boolean: When true, return only official-source rows and remove explicit fallback observations. Prohibited private aggregator rows are always removed regardless of this setting.
- `fields` string, nullable: Row field set. Omitted or `full` returns every documented row field. `compact` returns only `date`, `val`, `previous_value`, `change_from_previous`, `announcement_datetime`, `announcement_datetime_local` and `publication_time_status` per row, with the revision ledger folded into `revisions_summary` (`count`, `first`, `latest`, `revised`). The envelope, pagination and `dataset_version` are unchanged.
- `as_of` string, nullable
- `availability` 'public' | 'captured'
- `dataset_version` string, nullable
- `value_mode` 'normalized' | 'source'
- `api_key` string: Your Individual or Business API key

## Response `200`

Normalized macro series for one currency and indicator.

- AnnouncementResponse
  - `currency` string, required
  - `indicator` string, required
  - `name` string, nullable
  - `unit` string, nullable: Unit of `data[].val` in this response, from the series catalogue: the normalized unit by default, the percent unit of a derived `frequency` view (`%YoY`, `%QoQ`, `%MoM`), or `value_metadata.source_unit` when `value_mode=source`. Omitted when the catalogue declares no unit.
  - `value_name` string, nullable
  - `source` string, nullable
  - `source_url` string, nullable
  - `source_series_id` string, nullable
  - `source_series_name` string, nullable
  - `source_local_name` string, nullable
  - `seasonal_adjustment` string, nullable
  - `price_basis` string, nullable
  - `is_proxy` boolean
  - `proxy_note` string, nullable
  - `provenance` object: Publisher and source lineage for the served series.
    - `publisher` string, nullable
    - `publisher_url` string, nullable
    - `source_series_id` string, nullable
    - `source_series_name` string, nullable
    - `source_local_name` string, nullable
    - `seasonal_adjustment` string, nullable
    - `price_basis` string, nullable
    - `storage` string, nullable: Data provider label for the served series. Always `FXMacroData`.
    - `served_by` string, nullable: FXMacroData endpoint that serves this series.
    - `timestamp_field` string, nullable
    - `value_field` string, nullable
    - `is_proxy` boolean, nullable
    - `proxy_note` string, nullable
  - `policy_role` string, nullable
  - `policy_structure` string, nullable
  - `comparison_compatible` boolean, nullable
  - `policy_family` PolicyFamilyEntry[], nullable
    - `indicator` string, required
    - `value_name` string, required
    - `role` string, required
  - `has_official_forecast` boolean, required
  - `requested_start_date` string, nullable
  - `requested_end_date` string, nullable
  - `requested_window_has_data` boolean, nullable
  - `page_includes_latest_available` boolean, nullable
  - `start_date` string, required
  - `end_date` string, required
  - `earliest_available_date` string, nullable
  - `latest_available_date` string, nullable
  - `cb_target` CBTargetInfo: Central-bank target metadata for an indicator. ``current`` is the entry effective as of the response ``end_date``. ``history`` contains every known target regime in ascending date order.
    - `description` string, required
    - `source` string, required
    - `current` CBTargetEntry, required: A single central-bank target entry valid from ``effective_from``.
      - `effective_from` string, required
      - `target` number, nullable
      - `lower` number, nullable
      - `upper` number, nullable
      - `notes` string, nullable
    - `history` CBTargetEntry[], required
      - `effective_from` string, required
      - `target` number, nullable
      - `lower` number, nullable
      - `upper` number, nullable
      - `notes` string, nullable
  - `remap` object: Set when the requested indicator resolved to a canonical series.
    - `applied` boolean, nullable
    - `canonical_indicator` string, nullable
    - `rule_id` string, nullable
    - `transform` 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
  - `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
  - `replay` object, nullable
  - `dataset_version` string, nullable
  - `value_mode` 'normalized' | 'source'
  - `value_metadata` object, nullable
  - `pagination` PaginationInfo, required: Offset pagination state for a single page of results.
    - `limit` integer, nullable
    - `offset` integer, required
    - `returned_count` integer, required
    - `total_count` integer, required
    - `has_more` boolean, required
    - `next_offset` integer, nullable
    - `page_includes_latest_available` boolean, nullable
  - `freemium_window` FreemiumWindow: Present only when the freemium window shortened the response. Without it, ``pagination.total_count`` counts the clamped series and a truncated history is indistinguishable from a genuinely short one.
    - `applied` boolean, required
    - `max_days` integer, required
    - `cutoff_date` string, nullable
    - `message` string, nullable
  - `freemium_delay` FreemiumDelayNotice: How far behind real time a free-tier response is, and what that costs. Present only for callers without a paid key, and present whether or not anything was actually withheld: a delayed response must never be mistakable for a current one. ``withheld_count`` is how many releases were held back from *this* response; ``next_available_at`` is when the oldest of them becomes readable.
    - `applied` boolean, required
    - `delay_seconds` integer, required
    - `delay_minutes` integer, required
    - `cutoff` integer, required
    - `cutoff_iso` string, nullable
    - `withheld_count` integer, required
    - `message` string, required
    - `subscribe_url` string, required
    - `next_available_at` integer, nullable
    - `next_available_at_iso` string, nullable
  - `no_data` object, nullable
  - `data` AnnouncementDataPoint[], required
    - `source_validity_status` string, nullable: `invalid_source_capture` marks a proven source/parser mistake retained only in the raw source/all audit view. It is excluded from economic revision selection and point-in-time replay. Absence is not source verification.
    - `source_correction` object, nullable: Audit evidence for an incorrect source capture, including the observed and expected series identities and any official correction citation. Original values and capture clocks remain unchanged.
    - `announcement_id` string, nullable
    - `date` string, required
    - `val` number, nullable
    - `source` string, nullable
    - `source_url` string, nullable
    - `source_url_scope` 'release' | 'dataset' | 'series', nullable
    - `previous_value` number, nullable
    - `previous_date` string, nullable
    - `previous_announcement_datetime` integer, nullable
    - `change` number, nullable
    - `change_from_previous` number, nullable
    - `pct_change_from_previous` number, nullable
    - `original_val` number, nullable
    - `original_unit` string, nullable
    - `val_mom` number, nullable
    - `observation_id` string, nullable
    - `announcement_datetime` integer, nullable
    - `announcement_datetime_local` string, nullable
    - `release_time_assumed` boolean, nullable: Present and true when announcement_datetime was derived from the publication lag measured on this series' confirmed releases, because no official release calendar reaches the period. Omitted on rows whose publication time was captured from the release.
    - `release_time_upper_bound` boolean, nullable: Legacy estimate flag; does not establish point-in-time safety.
    - `publication_time_status` string, nullable: What `announcement_datetime` on this row actually is. Present on every row that carries a value. - `confirmed`: read from the publisher's own release - an embargo instant printed on the document, or a publication timestamp the source served with the data. - `unverified`: a real timestamp that this row does not evidence the origin of. Most historical rows are in this state. It is not an estimate, and it is not proof. - `assumed_historical`: derived by this service from the lag its own confirmed releases show. Only permitted where both the period and the estimated publication precede 2025-11-06; see `release_time_assumed`. - `unknown`: no publication time. `announcement_datetime` is null and the observation is served on its period date alone. Only `confirmed` is evidence of when the value became public. Gate point-in-time work on this field per row, never on a series-level claim.
    - `publication_time_precision` string, nullable: Resolution of `announcement_datetime`: `minute` when the publisher gave a clock time, `day` when only the release date was sourced, `unknown` otherwise.
    - `publication_time_basis` string, nullable: Where an `unverified` time came from: `official_schedule` means the publisher's own release calendar listed this release at this time (a planned time, equal to `official_planned_release_datetime`). Absent for `confirmed` rows, which carry the publisher's own timestamp for the release.
    - `vintage_status` string, nullable
    - `is_first_release` boolean, nullable
    - `observed_at_ns` integer, nullable
    - `observed_at_ns_string` string, nullable
    - `collected_at_ns_string` string, nullable
    - `publication_at_ns` integer, nullable: Publisher-sourced publication instant, Unix epoch nanoseconds (UTC). Present only when the source states one; omitted otherwise.
    - `publication_at_ns_string` string, nullable: `publication_at_ns` as a decimal string; present only alongside it.
    - `announcement_source_url` string, nullable: The specific release this value was read from - for USD CPI, the BLS archive page for that month's news release. Present only when a release-scoped citation is available; a dataset or landing-page URL is reported as `source_url` instead and is never promoted to this field.
    - `source_artifact_sha256` string, nullable
    - `capture_time_basis` string, nullable
    - `geography` string, nullable
    - `period_basis` string, nullable
    - `methodology_id` string, nullable
    - `source_period_label_conflict` boolean, nullable
    - `source_methodology_status` string, nullable
    - `selected_vintage_known_at_ns` string, nullable
    - `replay_vintage_verified` boolean, nullable
    - `official_planned_release_datetime` integer, nullable
    - `official_planned_release_datetime_local` string, nullable
    - `official_actual_release_datetime` integer, nullable
    - `official_actual_release_datetime_local` string, nullable
    - `collected_at_ns` integer, nullable
    - `collected_at_iso` string, nullable
    - `ingestion_latency_ms` number, nullable: Legacy stored nonnegative collection-minus-reference diagnostic in milliseconds, rounded to three decimals. Interpret only with `ingestion_latency_reference`; a planned reference measures from the schedule, not actual publication. Early captures clamp to zero. Use `release_timing` for separately evidenced publication/pickup bounds. Missing historical measurements are not synthesized.
    - `ingestion_latency_reference` string, nullable: Original clock for `ingestion_latency_ms`: `official_planned_release_datetime`, or `official_actual_release_datetime` when confirmed. Retained with the stored diagnostic; not reinterpreted as source-pickup or customer-delivery latency.
    - `release_timing` object: Scheduled, observed publication, capture and commit times for a release. Present on rows captured at release time from the official source. The publication window is bounded by FXMacroData's own reads of the official source; it is not a timestamp supplied by the publisher. Bounds that could not be established are null. Source pickup stops at accepted capture; legacy `latency_ms` and `pickup_ms_*` stop at the store commit. A null measurement does not establish whether a release was late.
      - `scheduled_at` string, nullable: Official scheduled release time (ISO 8601, UTC), or null when no exact time was scheduled. Latency is never measured from this time.
      - `published_at` string, nullable: The first observed read showing this period (ISO 8601, UTC, microsecond precision). This is an upper bound on publication, not an exact publisher timestamp. Same instant as `published_by`. Null when the capture did not record it.
      - `available_at` string, nullable: When this value was committed to the FXMacroData API data store (ISO 8601, UTC, microsecond precision). This clock does not measure client receipt. Null when the commit time was not recorded.
      - `latency_ms` number, nullable: Milliseconds from publication to `available_at`, measured from `published_after` (the last read still showing the previous period), so it is the longest the gap can have been. Never measured from the scheduled time. Null when publication was not bounded or `available_at` is missing.
      - `latency_reference` string, nullable: Reference for `latency_ms`: `publication_to_store_commit_upper_bound`. This legacy metric ends at the store commit; source capture is measured separately by `source_pickup_latency_min_ms` and `source_pickup_latency_max_ms`.
      - `publication_delay_ms` number, nullable: Milliseconds from `scheduled_at` to the observed upper publication bound `published_by`. This is a schedule diagnostic, not the actual publisher delay or pickup latency. Null when either timestamp is missing.
      - `published_after` string, nullable: The official source still showed the previous period after this instant (ISO 8601, UTC), or its `Last-Modified` header placed the update after it. Null when no such read was made.
      - `published_by` string, nullable: The first read of the official source that showed this period completed at this instant (ISO 8601, UTC), so the release was public by then. Null when the window could not be bounded.
      - `publication_window_basis` string, nullable: How the window was bounded: `poll_bracket` (a read showing the previous period, then a read showing this one), `last_modified` (the source's `Last-Modified` header sets the lower bound), or `first_new_period_read_only` (only the upper bound is known).
      - `collected_at` string, nullable: When FXMacroData first captured this value from the official source (ISO 8601, UTC). Same instant as `collected_at_iso`.
      - `pickup_ms_min` number, nullable: Milliseconds from `published_by` to `available_at`: the shortest time the value can have taken to reach store commit after publication, not edge availability or client receipt. Null when either time is missing or `available_at` precedes `published_by`.
      - `pickup_ms_max` number, nullable: Milliseconds from `published_after` to `available_at`: the value reached store commit within this long of publication (same figure as `latency_ms`), not edge availability or client receipt. Null when no read showed the previous period still in place, or when `available_at` is missing.
      - `picked_up_at` string, nullable: When FXMacroData accepted this value from the official source (ISO 8601, UTC, microsecond precision). This is separate from the store commit and from a source observation that could not be accepted. Null when the capture clock is unavailable.
      - `source_pickup_latency_min_ms` number, nullable: Minimum milliseconds from actual source publication to accepted pickup: `picked_up_at` minus `published_by`. Null when the required observation clocks are unavailable or inconsistent.
      - `source_pickup_latency_max_ms` number, nullable: Maximum milliseconds from actual source publication to accepted pickup: `picked_up_at` minus the proven lower publication bound. Null when that bound or a valid pickup clock is unavailable.
      - `source_pickup_latency_ms` number, nullable: Exact milliseconds from actual publication to accepted pickup. Null for observed publication windows because their bounds do not establish an exact publisher availability timestamp.
      - `source_pickup_outcome` string, nullable: `met` when the upper latency bound is below `source_pickup_slo_ms`; `breached` when the lower bound is at or above it; `unverified` when the evidence cannot decide; `not_observed` when no accepted pickup clock is recorded.
      - `source_pickup_reference` string, nullable: Evidence for pickup latency: `observed_publication_bracket`, `first_new_period_response_only`, `unverified_publication_clock`, or `source_pickup_not_observed`. A scheduled time is never used as the publication reference.
      - `source_pickup_slo_ms` number, nullable: The strict latency threshold, in milliseconds, used to classify source pickup. The default is 1000 milliseconds.
    - `pct_change` number, nullable
    - `pct_change_yoy` number, nullable
    - `pct_change_qoq` number, nullable
    - `pct_change_mom` number, nullable
    - `pct_change_12m` number, nullable
    - `revisions` RevisionEntry[], nullable
      - `epoch` integer, nullable
      - `val` number, nullable
      - `observed_at_ns` integer, nullable
      - `observed_at_ns_string` string, nullable
      - `publication_at_ns` integer, nullable: Publisher-sourced publication instant, Unix epoch nanoseconds (UTC). Present only when the source states one; omitted otherwise.
      - `publication_at_ns_string` string, nullable: `publication_at_ns` as a decimal string; present only alongside it.
      - `announcement_source_url` string, nullable
      - `capture_time_basis` string, nullable
      - `publication_time_status` string, nullable
      - `publication_time_precision` string, nullable
      - `vintage_status` string, nullable
      - `is_first_release` boolean, nullable
      - `source_url` string, nullable
      - `source_artifact_sha256` string, nullable
      - `change` number, nullable
      - `source_validity_status` string, nullable: `invalid_source_capture` marks a proven source/parser mistake retained only in the raw source/all audit view. It is excluded from economic revision selection and point-in-time replay. Absence is not source verification.
      - `source_correction` object, nullable: Audit evidence for an incorrect source capture, including the observed and expected series identities and any official correction citation. Original values and capture clocks remain unchanged.
    - `revisions_summary` RevisionsSummary: Revision ledger summary served by ``fields=compact``.
      - `count` integer, required: Number of retained value groups; repeated consecutive captures may be grouped. Not a count of verified publisher revisions.
      - `first` number, nullable: Earliest retained value in this view; not proof of the publisher's first release.
      - `latest` number, nullable: Latest retained value in this view; not proof of publisher finality.
      - `revised` boolean, required: True when a later retained value differs from the earliest retained value.
    - `outside_requested_window` boolean, nullable
    - `requested_start_date` string, nullable
    - `requested_end_date` string, nullable
    - `returned_reason` string, nullable
    - `staleness_days` integer, nullable
    - `canonical_indicator` string, nullable
    - `raw_indicator` string, nullable
    - `remap_applied` boolean, nullable
    - `remap_rule_id` string, nullable
    - `remap_segment_id` string, nullable

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