# Response Fields: Announcement Row, Revisions, Timing | FXMacroData API

> One-line definitions of every field on an FXMacroData announcement row: date, val, previous_value, change_from_previous, announcement_datetime, publication_time_status, release_timing, revisions, vintage_status, availability and point_in_time_safe, plus the response envelope and data_quality.

Source: https://fxmacrodata.com/documentation/response-fields
Documentation index: https://fxmacrodata.com/documentation/llms.txt
API base URL: https://api.fxmacrodata.com

# Response fields

Every field you can meet on an announcement row, in its revisions and release timing, and in the envelope around it, defined in one line each. The definitions follow the production OpenAPI schema; the [announcements endpoint](https://fxmacrodata.com/documentation/announcement-endpoint) page explains how the series are built, and [point-in-time backtesting](https://fxmacrodata.com/documentation/point-in-time-backtesting) shows the fields in use.

## How to read a row

Three questions decide how a row can be used.

### What is the value?

`date` is the period, `val` the value in the normalised unit, `original_val` and `original_unit` the publisher's own print. `previous_value` and `change_from_previous` compare it with the row before.

### When did it become public?

`announcement_datetime` is the publication instant, and `publication_time_status` says what kind of evidence stands behind it. `release_timing` bounds the publication and shows when the value was readable through the API.

### Which vintage is it?

`vintage_status`, `is_first_release` and `revisions[]` tell first prints from revisions. With `as_of`, `availability` picks the clock and `data_quality.point_in_time_safe` says whether the whole response is replay-safe.

## Announcement row

Each element of data[] on /v1/announcements/{currency}/{indicator}, /v1/latest/announcements/... and /v1/recent/announcements/... is one published observation. Fields are omitted when they do not apply to the row, so read them as optional unless marked required.

| Field | Type | Definition |
| --- | --- | --- |
| date | string, required | Reference period of the observation as YYYY-MM-DD. |
| val | number or null | Value in the normalised unit named by the response metadata; null when the publisher released a placeholder. |
| original_val | number | Value exactly as the publisher printed it, before unit normalisation. Present when it differs from val. |
| original_unit | string | Publisher's unit for original_val. |
| announcement_id | string | Stable identifier of this release row. |
| observation_id | string | Identifier of the observation (period) this row describes, shared across its vintages. |
| source | string | Name of the official publisher the value was read from. |
| source_url | string | URL the value was read from. |
| source_url_scope | release \| dataset \| series | What source_url points at: the specific release document, the dataset it belongs to, or the series landing page. |
| announcement_source_url | string | Release-scoped citation such as the publisher's news-release page for this period. Present only when a release-level URL exists; dataset and landing-page URLs stay in source_url. |
| source_artifact_sha256 | string | SHA-256 digest of the source document the value was read from, for independent verification. |
| previous_value | number | Value of the preceding row in the series. |
| previous_date | string | Reference period of the preceding row. |
| previous_announcement_datetime | integer | Publication time of the preceding row, Unix epoch seconds (UTC). |
| change | number | Headline movement the publisher itself reports, on series where the official print is a change (for example non-farm payrolls). Absent elsewhere. |
| change_from_previous | number | val minus previous_value, computed by FXMacroData. Omitted on series whose publisher supplies the headline change. |
| pct_change_from_previous | number | Percentage difference between val and previous_value. |
| pct_change_yoy, pct_change_qoq, pct_change_mom, pct_change_12m, pct_change, val_mom | number | Derived percentage changes over the named horizon. Present when the series supports that transform; the frequency query parameter selects which one becomes val. |
| announcement_datetime | integer or null | When the value was published, Unix epoch seconds (UTC). Null when publication_time_status is unknown; what the number means is stated by publication_time_status. |
| announcement_datetime_local | string | The same instant written in the publisher's local time zone. |
| publication_time_status | string | What announcement_datetime actually is: confirmed, unverified, assumed_historical or unknown. See the values below. Gate point-in-time work on this per row. |
| publication_time_precision | minute \| day \| unknown | Resolution of announcement_datetime: minute when the publisher gave a clock time, day when only the release date was sourced. |
| publication_time_basis | string | Where an unverified time came from. official_schedule means the publisher's own calendar listed the release at this time. Absent on confirmed rows. |
| release_time_assumed | boolean | True when announcement_datetime was derived from the publication lag measured on this series' confirmed releases. Only permitted where both the period and the estimated publication precede 2025-11-06. |
| release_time_upper_bound | boolean | Legacy estimate flag kept for older rows; it does not establish point-in-time safety. |
| publication_at_ns, publication_at_ns_string | integer, string | Publication instant stated by the publisher, Unix epoch nanoseconds (UTC), and the same value as a decimal string. Present only when the source states one. |
| observed_at_ns, observed_at_ns_string | integer, string | When FXMacroData observed this value at the source, Unix epoch nanoseconds (UTC). |
| collected_at_ns, collected_at_ns_string, collected_at_iso | integer, string, string | When FXMacroData first captured this value from the official source, as epoch nanoseconds and ISO 8601. |
| capture_time_basis | string | Which moment the capture time records: fetch_completed (the read that returned the value finished) or first_fresh_fetch_completed (the first read that showed the new period finished). |
| official_planned_release_datetime, official_planned_release_datetime_local | integer, string | Release time scheduled in the publisher's own calendar, as epoch seconds and local time. |
| official_actual_release_datetime, official_actual_release_datetime_local | integer, string | Release time the publisher recorded for the actual publication, where it publishes one. |
| vintage_status | string | source_vintage when the value is a vintage the publisher released; legacy_snapshot when it is a stored snapshot that predates vintage tracking. |
| is_first_release | boolean | True when this value is the first print for the period rather than a revision. |
| selected_vintage_known_at_ns | string | With as_of: the instant the returned vintage became known, Unix epoch nanoseconds, as a decimal string. |
| replay_vintage_verified | boolean | With as_of: true when the returned vintage is proven to have been knowable at that instant under the chosen availability basis. |
| release_timing | object | Scheduled, published, collected and available times for a release captured at release time. Fields below. |
| revisions | array | Every published value recorded for this period, newest last, when the request asks for revisions=all. Entry fields below. |
| revisions_summary | object | count of distinct published values, first and latest value, and revised (true when a later vintage changed the first print). |
| outside_requested_window | boolean | True when the row lies before the requested window and is returned as the latest official observation preceding it. |
| requested_start_date, requested_end_date | string | The window the caller asked for, echoed on an outside-window row. |
| returned_reason | string | Why an outside-window row was returned: latest_official_observation_before_requested_window. |
| staleness_days | integer | Days between the requested start date and the date of the outside-window row returned in its place. |
| geography, period_basis, methodology_id, source_methodology_status, source_period_label_conflict | string, string, string, string, boolean | Series metadata carried on the row: geographic scope, how the period is defined, the methodology identifier, the publisher's methodology status, and whether the publisher labelled the period differently from the stored date. |
| canonical_indicator, raw_indicator, remap_applied, remap_rule_id, remap_segment_id | string, string, boolean, string, string | With series_mode=canonical: the canonical slug the row is served under, the stored slug it came from, and the continuity rule that mapped it. |

## release_timing

Present on rows captured at release time from the official source. The publication window is bounded by FXMacroData's own reads of the source; it is not a timestamp supplied by the publisher. All times are ISO 8601 UTC.

| Field | Type | Definition |
| --- | --- | --- |
| scheduled_at | string or null | Official scheduled release time. Latency is never measured from this time. |
| published_at | string or null | When the official source actually published the value: the first read of the source that showed this period, microsecond precision. Same instant as published_by. |
| available_at | string or null | When the value was committed to the FXMacroData store and readable through the API, microsecond precision. Null on rows captured before this time was recorded. |
| latency_ms | number or null | Milliseconds from publication to available_at, measured from published_after so it is the longest the gap can have been. Never measured from the scheduled time. |
| publication_delay_ms | number or null | Milliseconds from scheduled_at to published_at: how long after the scheduled time the source published (negative when early). |
| published_after | string or null | The source still showed the previous period after this instant, or its Last-Modified header placed the update after it. Null when no such read was made. |
| published_by | string or null | The first read of the source that showed this period completed at this instant, so the release was public by then. Null when the window could not be bounded. |
| publication_window_basis | string or null | How the window was bounded: poll_bracket (a read showing the previous period, then one showing this period), 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 or null | When FXMacroData first captured this value from the source. Same instant as collected_at_iso. |
| pickup_ms_min | number or null | Milliseconds from published_by to available_at: the shortest time the value can have taken to become available after publication. |
| pickup_ms_max | number or null | Milliseconds from published_after to available_at: the value was available through the API within this long of publication. Null when no read showed the previous period still in place. |

## revisions[] entry

One published value for the period, identified by its release epoch. val is null when the publisher released a placeholder for that vintage.

| Field | Type | Definition |
| --- | --- | --- |
| epoch | integer | Publication time of this vintage, Unix epoch seconds (UTC). |
| val | number or null | Value published in this vintage. |
| change | number | Difference between this vintage and the one before it. |
| is_first_release | boolean | True for the first print of the period. |
| vintage_status | string | source_vintage or legacy_snapshot, as on the row. |
| publication_time_status, publication_time_precision | string | Evidence class and resolution of epoch, with the same values as on the row. |
| publication_at_ns, publication_at_ns_string | integer, string | Publisher-stated publication instant in epoch nanoseconds, when the source states one. |
| observed_at_ns, observed_at_ns_string | integer, string | When FXMacroData observed this vintage at the source. |
| capture_time_basis | string | Which moment the capture time records, as on the row. |
| source_url, announcement_source_url, source_artifact_sha256 | string | Where this vintage was read from and the digest of that document. |

## Response envelope

Top-level fields on /v1/announcements/{currency}/{indicator} around data[].

| Field | Type | Definition |
| --- | --- | --- |
| currency, indicator | string | Currency code and indicator slug the response is for. |
| name, value_name | string | Display name of the series and of the value it reports. |
| source, source_url, source_series_id, source_series_name, source_local_name | string | Publisher, its URL, the publisher's own series identifier and name, and the series name in the publisher's language. |
| seasonal_adjustment, price_basis | string | Whether the series is seasonally adjusted, and whether prices are real or nominal, as published. |
| is_proxy, proxy_note | boolean, string | True when the series stands in for a concept the publisher does not release directly, with the note explaining the proxy. |
| provenance | object | Publisher, storage, served_by, timestamp_field and value_field: how the served rows were produced. |
| policy_role, policy_structure, policy_family, comparison_compatible | string, string, array, boolean | For policy-rate series: the role of this rate in the central bank's framework, the structure (single rate, corridor, band), the related rates, and whether it is comparable across currencies. |
| has_official_forecast | boolean, required | True when the publisher releases an official forecast for this series. |
| start_date, end_date | string, required | Window the returned rows cover after window rules and free-tier limits are applied. |
| requested_start_date, requested_end_date, requested_window_has_data, page_includes_latest_available | string, string, boolean, boolean | What the caller asked for, whether any row falls inside it, and whether this page contains the newest available observation. |
| earliest_available_date, latest_available_date | string | First and last observation dates stored for the series. |
| cb_target | object | For inflation series: the central bank's target with its history (effective_from, target, lower, upper, notes). |
| remap, filters, selected_series_id, selected_series | object | Which series variant the request resolved to and the selectors (seasonality, frequency, revisions, annualization, period_aggregation, basis) that chose it. |
| supported_options | object | Selector values this endpoint accepts, keyed by selector name. Unsupported values return unsupported_series_option. |
| data_quality | object, required | Quality summary for the returned rows. Key fields below. |
| replay | object | With as_of: the replay cutoff (as_of, as_of_ns), the availability mode, the dataset_version hash, and per-series evidence. |
| dataset_version | string | Hash of the sources and value settings behind the response. Send it back as dataset_version to be told (409 dataset_version_changed) when a replay would no longer be reproducible. |
| value_mode, value_metadata | string, object | normalized (default) or source; value_metadata states the source unit and whether normalisation was applied. |
| pagination | object, required | limit, offset, returned_count, total_count, has_more, next_offset and page_includes_latest_available. |
| freemium_window | object | Present when free access clamped the window: applied, max_days, cutoff_date and message. |
| freemium_delay | object | Present when free access withheld recent releases: applied, delay_seconds, delay_minutes, cutoff, cutoff_iso, withheld_count, message, subscribe_url, next_available_at and next_available_at_iso. |
| no_data | object | Present on a valid series with no rows in the requested window, explaining why. |

## data_quality

Fields most callers gate on. The object carries further counters that follow the same naming.

| Field | Type | Definition |
| --- | --- | --- |
| point_in_time_safe | boolean | Whether the returned values have verified availability and vintage evidence. Estimated release times never qualify. |
| point_in_time_basis | string | With as_of: source_publication when availability=public, value_capture when availability=captured. |
| source_type | official \| public \| fallback \| derived | What kind of source produced the rows. |
| is_official, is_proxy, is_fallback, is_derived | boolean | Source classification flags for the rows returned. |
| is_stale, stale_after_days, data_lag_days | boolean, integer, integer | Whether the newest observation is older than the series' freshness threshold, that threshold, and the publisher's usual lag. |
| source_freshness, source_monitoring_complete, known_source_gap, source_checked_at, source_check_expires_at, latest_published_period | string, boolean, boolean, integer, integer, string | Result of the last check against the publisher: whether a newer period is known to exist upstream and when the check was made. |
| has_announcement_datetime, announcement_datetime_count, missing_announcement_datetime_count, row_count | boolean, integer, integer, integer | How many returned rows carry a publication time. |
| unverified_vintage_count, unknown_publication_time_count | integer | Rows whose vintage or publication time is not evidenced. |
| has_assumed_release_times, assumed_release_time_count, bounded_release_time_count, unbounded_release_time_count | boolean, integer, integer, integer | Rows whose publication time was derived rather than captured, and how many of those carry an availability bound. |
| quality_scope | string | Which rows the summary describes: the requested window, the page, latest, or recent. |
| requested_window_has_data, requested_window_latest_date, returned_latest_available_before_window, staleness_days, reason | boolean, string, boolean, integer, string | Window outcome: whether the window had rows, the newest date inside it, and whether an older row was returned in its place. |
| latest_available_date, last_updated | string | Newest stored observation and when the series was last refreshed. |
| datetime_field, datetime_precision, datetime_semantics | string | Which field carries the row's time, at what resolution, and what that time means. |

## publication_time_status values

Present on every row that carries a value. Only confirmed is evidence of when the value became public.

| Value | Meaning |
| --- | --- |
| 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 whose origin this row does not evidence. Most historical rows are in this state. It is not an estimate, and it is not proof. |
| assumed_historical | Derived by FXMacroData from the lag its own confirmed releases show. Only permitted where both the period and the estimated publication precede 2025-11-06; release_time_assumed is true. |
| unknown | No publication time. announcement_datetime is null and the observation is served on its period date alone. |

## vintage_status values

States whether a value is a publisher vintage or an older stored snapshot.

| Value | Meaning |
| --- | --- |
| source_vintage | The value is a vintage the publisher released and FXMacroData captured as such. |
| legacy_snapshot | The value is a stored snapshot from before vintage tracking; it may not be the first print for its period. |

## availability values (with as_of)

Chooses which clock decides whether a value was knowable at as_of.

| Value | Meaning |
| --- | --- |
| public | Default. A value counts as known once the publisher released it; data_quality.point_in_time_basis is source_publication. |
| captured | A value counts as known once FXMacroData had captured it; data_quality.point_in_time_basis is value_capture. |

## revisions values

Selects which vintage fills val for each period.

| Value | Meaning |
| --- | --- |
| latest | Default. The most recent published value for each period. |
| first | The first print for each period. |
| final | The final published value for each period. |
| all | The latest value in val, with every vintage listed under revisions[] and summarised in revisions_summary. |

## source_url_scope values

What kind of page source_url is.

| Value | Meaning |
| --- | --- |
| release | The specific release document for this period. |
| dataset | The dataset or table the value belongs to. |
| series | The publisher's series landing page. |

## Related

- [API reference](https://fxmacrodata.com/documentation/reference): every endpoint, with the interactive OpenAPI schema for the exact types.

- [Low-latency reads](https://fxmacrodata.com/documentation/low-latency): the same row shape returned by `/v1/latest` and `/v1/recent`.

- [Data quality](https://fxmacrodata.com/documentation/data-quality): how sources are classified and freshness is measured.

- [Deprecation policy](https://fxmacrodata.com/documentation/deprecation-policy): which changes to these fields can happen without notice and which cannot.