--- title: "Poll recent live announcement release changes" method: GET path: "/v1/announcements/changes" tags: ["announcements"] --- # Poll recent live announcement release changes `GET /v1/announcements/changes` ## Request - Base URL: `https://api.fxmacrodata.com` - URL: `https://api.fxmacrodata.com/v1/announcements/changes` - Auth: one of: - none - API key in header `X-API-Key` - HTTP bearer Returns recent live announcement release events from the same durable fanout used by the real-time SSE stream. Use `next_cursor` as the `since` value on the next poll. This endpoint is intended for serverless clients that cannot hold a persistent SSE connection. **Authentication:** USD events are available without an API key. Non-USD currencies require a paid API key supplied via `api_key` or `X-API-Key`. **Free access is delayed.** Without an API key this feed is held back by 15 minutes: an event is delivered once it is 15 minutes old, and `next_cursor` stops at the delay cutoff so nothing is skipped. The response carries a `freemium_delay` object naming the cutoff, how many events are being withheld, and when the next one becomes available. An Individual or Business API key removes the delay; `/v1/stream/events` pushes the same events in real time. **Retention:** Events are retained for the configured fanout window, currently exposed in `retention_seconds`. If a client is offline longer than that window, re-bootstrap from `/v1/announcements/{currency}/latest` and continue polling changes. ## Query parameters - `currencies` string, nullable: Comma-separated currency codes, `g10`, or `all`. Without a paid API key the result is restricted to USD. - `indicators` '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', nullable: Optional comma-separated announcement indicator slugs. - `since` string, nullable: Cursor returned as `next_cursor` by the previous response. ISO 8601 timestamps and Unix epoch seconds are also accepted. - `limit` integer: Maximum number of matching change events to return. - `payload` 'compact' | 'full', nullable: Use `compact` for trigger payloads or `full` for row fields. - `api_key` string, nullable ## Response `200` Successful Response - AnnouncementChangesResponse - `data` AnnouncementChangeEvent[], required - `event_id` string, required - `currency` string, required - `indicator` string, required - `records_written` integer, nullable - `timestamp` union - integer - number - `release_timestamp` union - integer - number - `latest_announcement` ReleaseDeliveryAnnouncement: The announcement row carried by a release event. Additional fields may appear as the announcement data model grows; clients should ignore fields they do not recognise. - `date` string, nullable - `original_val` union - integer - number - `original_unit` string, nullable - `val` union - integer - number - `announcement_datetime` union - integer - number - `source` string, nullable - `source_url` string, nullable - `source_url_scope` string, nullable - `source_release` string, nullable - `release_url` string, nullable - `dataset_url` string, nullable - `series_url` string, nullable - `delivery_mode` string, nullable - `origin_delivery_mode` string, nullable - `source_fresh_at_ns` union - integer - number - `stream_ready_at_ns` union - integer - number - `server_sent_at_ns` union: Time FXMacroData sent this event, as Unix epoch nanoseconds (UTC). - integer - number - `acknowledgement_endpoint` string, nullable: Endpoint for acknowledging receipt of a streamed event. Present only on `/v1/stream/events` deliveries; never set on `/v1/announcements/changes`. - `age_ms` union: Event age in milliseconds when it was sent. Present only on `/v1/stream/events` deliveries; never set on `/v1/announcements/changes`. - integer - number - `stale_after_ms` union: Age in milliseconds after which a streamed event is considered stale. Present only on `/v1/stream/events` deliveries; never set on `/v1/announcements/changes`. - integer - number - `stale` boolean, nullable: True when the event was older than `stale_after_ms` when sent. Present only on `/v1/stream/events` deliveries; never set on `/v1/announcements/changes`. - `late_delivery` boolean, nullable: True when the event was sent after its staleness threshold. Present only on `/v1/stream/events` deliveries; never set on `/v1/announcements/changes`. - `late_events_are_delivered` boolean, nullable - `scheduled_release_at_ns` union - integer - number - `scheduled_to_server_send_ms` union: Milliseconds from the scheduled release time to the time FXMacroData sent this event. - integer - number - `source_late` boolean, nullable - `source_late_by_ms` union - integer - number - `source_delay_proven` boolean, nullable - `platform_delivery_after_source_ms` union - integer - number - `polling_started_at_ns` union - integer - number - `polling_started_lag_ms` union - integer - number - `polling_started_before_scheduled_release` boolean, nullable - `pre_fresh_stale_poll_count` union - integer - number - `last_stale_fetch_completed_at_ns` union - integer - number - `first_fresh_response_completed_at_ns` union - integer - number - `official_source_stale_after_scheduled_release` boolean, nullable - `scheduled_to_first_fresh_response_ms` union - integer - number - `source_freshness_observation_window_start_at_ns` union - integer - number - `source_freshness_observation_window_end_at_ns` union - integer - number - `source_freshness_observation_window_ms` union - integer - number - `source_freshness_observation_basis` string, nullable - `source_delay_attribution` string, nullable - `fxmd_delivery_attribution` string, nullable - `fxmd_after_source_ms` union - integer - number - `fxmd_after_source_slo_met` boolean, nullable - `catchup_source` string, nullable - `catchup_delay_ms` union - integer - number - `recovery_class` string, nullable - `subsecond_status` string, nullable - `subsecond_operational_status` string, nullable - `subsecond_guarantee_active` boolean, nullable - `subsecond_contract_outcome` string, nullable - `subsecond_contract_breached` boolean, nullable - `count` integer, required - `next_cursor` string, required - `has_more` boolean, required - `retention_seconds` integer, required - `scope` AnnouncementChangesScope, required: The filter set the response was produced under. ``currencies`` and ``indicators`` are null when no filter was applied. - `currencies` string[], nullable - `indicators` string[], nullable - `payload` 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 ## 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)