Documentation

API Changelog

Material endpoint contract changes for the FXMacroData API: response schemas, endpoint lifecycle changes, authentication behavior, rate limits, and streaming payload changes.

OpenAPI schema API reference Issue log

2026-10-16 Announcement release timing fields and publisher names

Added Announcement rows carry an additive release_timing object; no existing field changes meaning. scheduled_at is the official scheduled time. published_after and published_by bracket when the figure actually appeared at the publisher: the last read still showing the previous figure and the first read showing the new one. published_at equals published_by and is null when no publication read was recorded; it is never filled in from the schedule.
Added picked_up_at is when FXMacroData accepted the new figure from the publisher, and available_at is when it was committed to our database and became readable. source_pickup_latency_min_ms and source_pickup_latency_max_ms run from the publication bracket to picked_up_at; latency_ms, pickup_ms_min and pickup_ms_max run from the publication bracket to available_at. Latency is always measured from the actual publication, never from the scheduled time. source_pickup_latency_ms stays null because publishers do not expose an exact release clock, and any figure without evidence is null rather than estimated. publication_delay_ms describes the publisher against its own schedule and is not a pickup latency.
Changed ingestion_latency_ms and ingestion_latency_reference keep their original values and meaning when stored. They remain deprecated diagnostics, not a publication-to-pickup latency; use release_timing for latency. See the migration guidance.
Changed Full announcement responses keep every retained revision entry with its own capture clock. Grouped revision summaries are available on request with fields=compact.
Changed source on announcement rows names the publisher for every catalogue series (for example RBA) instead of a generic label. Rolling statistical tables, such as the RBA A1 and D3 CSV files, are cited with source_url_scope=dataset; period-specific release pages keep source_url_scope=release.
Changed Webhook announcement events deliver val, previous and previous_announcement on the same scale and unit as the announcements endpoint and the SSE stream, so they match the event's forecast and the catalogue unit. For example, sentiment indices are delivered on the 0-100 normalized scale and employment levels in persons. Where a value is rescaled, original_val and original_unit keep the publisher's own reading and unit.
Added Webhook announcement rows carry publication_time_status (confirmed, unverified or unknown) and the nullable official_planned_release_datetime, the scheduled time on the publisher's calendar. announcement_datetime is null when the publication time is not yet known. When a delivered value later gains its publication time, a second announcement event with its own event_id re-sends the completed row with data.update_reason set to publication_time_updated and data.update_of_event_id naming the original event. See the webhooks documentation.

2026-10-10 Announcement capture history and timing compatibility

Changed Full announcement latest and all views preserve separate retained captures, including equal values with different clocks or source artifacts. This restores the capture history grouped on 6 October. Explicit fields=compact keeps its summary format.
Changed Optional ingestion_latency_ms and ingestion_latency_reference are retained when stored and marked deprecated. Their original collection diagnostic remains separate from release_timing publication and pickup bounds. No removal date is set; at least six calendar months of public notice is required. See the migration guidance.
Added Single-series downloads accept revision_evidence=full to retain eligible revision evidence and exact capture-clock strings. CSV downloads use a ZIP with an evidence sidecar; ordinary download formats and normalized value defaults remain unchanged.

2026-10-06 Rate-limit headers, compact rows, COT report types, bulk downloads

Added Every API response now carries IETF RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers, and 429 responses set Retry-After to the same reset. See the rate-limit guide.
Added /v1/announcements/{currency}/{indicator} accepts fields=compact, returning the essential fields per row (date, value, previous value, change, announcement time, publication-time status and a revisions summary). This release also grouped consecutive unchanged captures in full revisions[]; the 10 October compatibility update restores those separate retained entries.
Added /v1/cot/{currency} and /latest accept report=legacy_futures|legacy_combined|tff_futures|tff_combined|disaggregated_futures. The default (Legacy futures-only) response is byte-identical; the Traders in Financial Futures categories (dealer, asset manager, leveraged funds, other reportables) are new fields with z-scores. Gold (XAU) is served from the Disaggregated report.
Added Data export supports format=parquet, and subscribers can download one full-history file per currency at /data-export/bulk/{currency}.parquet or .csv.zip, rebuilt daily.
Changed 401 responses from the edge and the origin share one body shape (code, detail, subscribe_url) and now include a free_example URL that works without a key.
Changed Calendar top_tier_for_currency is now genuinely per-currency (for example NZD dairy exports, JPY Tankan, BRL IPCA-15); market_tier is promoted to 1 for those rows so the two fields never disagree. COT and press-release currency lists only advertise production currencies.
Removed POST /v1/summarize, an undocumented text-trimming helper, has been removed.

2026-07-18 Predictions response groups forecasts by announcement

Changed The GET /v1/predictions/{currency}/{indicator} response now returns one data[] group per announcement_id. Forecast values live under data[].predictions[], so clients that previously read data[0].predicted_value should now read data[0].predictions[0].predicted_value or choose a specific entry by prediction_source.
Added Each prediction item can include prediction_type, prediction_source, prediction_source_label, generated_at, confidence, and prediction_reason. This supports multiple forecast sources for the same scheduled announcement.
Changed Prediction groups use the same announcement_id join key as announcement history, making it easier to connect forecast records with realised observations after release.

2026-07-14 Calendar, announcements, and predictions contract clarified

Changed The public endpoint contract is now documented as three distinct surfaces: GET /v1/calendar/{currency} for upcoming release schedules, GET /v1/announcements/{currency}/{indicator} for realised values and prior observations, and GET /v1/predictions/{currency}/{indicator} for forecast groups keyed by announcement_id.
Changed Calendar rows should be treated as schedule rows. Forecast and consensus values belong on the predictions endpoint, not on calendar responses.

2026-05-18 Rate-limit tiers published · per-key concurrency cap

Added A per-key in-flight concurrency cap limits accidental single-key request fanouts that could otherwise degrade latency for other users. Keys default to 20 concurrent requests.
Added 429 responses now include an X-RateLimit-Window header identifying which budget tripped (minute, hour, day, endpoint, or concurrency) so clients can self-throttle the right dimension.
Changed Concurrency caps are designed for accidental fanout protection, not normal production request patterns. ETag / If-None-Match responses continue to avoid quota counting.

2026-03-30 Press-release and risk-sentiment endpoints added

Added Endpoint added: GET /v1/press-releases/{currency}. Responses return a paginated press-release feed with currency, count, and data[] records containing release titles, URLs, dates, summaries, and policy-context fields where available.
Added Endpoint added: GET /v1/risk_sentiment. Responses return a daily risk-on/risk-off score with score, regime, component metadata, data-quality metadata, and pagination fields.

2026-03-29 GDP response fields added

Added GDP announcement responses now include pct_change_qoq and pct_change_yoy fields alongside the absolute output level. No client-side calculation needed.

2026-03-27 Per-key rate limits

Added Per-key rate limiting is enforced on all endpoints. Limits are documented in the rate limits guide.

2026-03-25 Live event streaming endpoint added

Added Endpoint added: GET /v1/stream/events for Server-Sent Events delivery of announcement events.
Added SSE clients can filter events with currencies and indicators, and can reconnect with Last-Event-ID to replay buffered events.
Added Stream events include stable identifiers and routing fields such as event_id, currency, indicator, records_written, and timestamp.

2026-03-25 COT, commodities, and calendar contracts changed

Changed GET /v1/cot/{currency} access now follows the same mixed-access pattern as announcements: USD requests are publicly accessible, while other currencies require a valid API key.
Changed GET /v1/commodities/{indicator} now requires a valid API key for every request.
Added Release-calendar rows can include additive routing metadata such as domain, endpoint_family, and endpoint_path, while keeping announcement_datetime and release stable.

2026-03-24 MCP transport endpoint added

Added MCP transport added at https://mcp.fxmacrodata.com for compatible clients. Authentication uses OAuth 2.0 + PKCE.
Added The MCP tool catalogue exposes announcement, release-calendar, data-catalogue, COT, commodities, and market-session query surfaces.

2026-03-23 GraphQL query interface

Added GraphQL endpoint added at POST /v1/graphql. Query indicator announcements, release calendars, and data catalogue entries using standard GraphQL syntax. Authenticate with a valid API key.

2025-11-13 Breaking change: policy_rate replaces interest_rates slug

Changed The indicator slug interest_rates is replaced by policy_rate across all currencies. Update your API calls — the old slug no longer works.

2025-11-06 Public API launch

Added FXMacroData public REST API launched with stable endpoint families for announcements, release calendars, data catalogue discovery, COT positioning, and commodities.
Added Release calendar endpoint launched: GET /v1/calendar/{currency} — lists upcoming economic data releases with scheduled announcement times.
Added COT positioning endpoint launched: GET /v1/cot/{currency} — weekly CFTC Commitment of Traders data for G8 futures contracts.
Added Commodities endpoint launched: GET /v1/commodities/{indicator} — daily energy prices (WTI, Brent, Natural Gas) and precious metals.
Added Data catalogue endpoint launched: GET /v1/data_catalogue/{currency} — discover which indicators are available for each currency, with metadata.

API Changelog

Key Facts

Quick Q&A