Previous value: -"Existing canvas ID to accumulate results into across multiple queries. Omit to allocate a fresh canvas; the response includes a canvas_id when results spill to DataCanvas."New value: +"Existing canvas ID to accumulate results into across multiple queries. This selects the destination only; it does not force staging. Use output_mode=\"canvas\" to stage an under-budget result."

Added value: +{
+  "default": "auto",
+  "description": "Result placement. auto returns an under-budget result inline and spills only when needed. canvas explicitly stages the full result, using canvas_id when supplied or allocating a fresh canvas.",
+  "enum": [
+    "auto",
+    "canvas"
+  ],
+  "type": "string"
+}

Previous value: -"Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result."New value: +"Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or a calendar-valid YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result."

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "dataflow_id",
-      "key",
-      "observations",
-      "series_attributes",
-      "observation_count",
-      "truncated",
-      "source"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dataflow_id",
+      "key",
+      "observations",
+      "series_attributes",
+      "observation_count",
+      "staged",
+      "truncated",
+      "source"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Previous value: -"DataCanvas session ID — present when truncated=true. Pass to imf_dataframe_query or imf_dataframe_describe to query the full result."New value: +"DataCanvas session ID — present when staged=true. Pass first to imf_dataframe_describe, then to imf_dataframe_query."

Previous value: -"Machine-readable failure mode. Declared by this tool: `dataflow_not_found`: dataflow_id does not match any known dataflow on api.imf.org `no_data`: Key is structurally valid but the dataflow holds no series for this code combination, or the dataflow publishes no series at all `no_data_in_range`: The key returned observations but start_period/end_period excluded every one of them `key_dimension_mismatch`: Number of dot-separated segments in key does not match the dataflow's DSD dimension count `empty_key_segment`: A dot-separated position in key is empty or blank, which matches no series upstream `invalid_period_format`: start_period or end_period is not one of the recognized period formats `invalid_period_range`: start_period is later than end_period `structure_unavailable`: api.imf.org returns non-200 on the data endpoint `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD and data lookups are attempted Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `dataflow_not_found`: dataflow_id does not match any known dataflow on api.imf.org `no_data`: Key is structurally valid but the dataflow holds no series for this code combination, or the dataflow publishes no series at all `no_data_in_range`: The key returned observations but start_period/end_period excluded every one of them `key_dimension_mismatch`: Number of dot-separated segments in key does not match the dataflow's DSD dimension count `empty_key_segment`: A dot-separated position in key is empty or blank, which matches no series upstream `invalid_period_format`: start_period or end_period is not one of the recognized period formats `invalid_period_range`: start_period is later than end_period `structure_unavailable`: The dataflow structure (DSD) cannot be fetched after the dataflow catalog resolved successfully `canvas_unavailable`: output_mode=\"canvas\" was requested but DataCanvas is disabled `response_too_large`: Fixed staged-result metadata exceeds the response budget before any observation preview can be included `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD and data lookups are attempted Other values are possible when a failure originates below the handler."

Previous value: -[
-  "dataflow_not_found",
-  "no_data",
-  "no_data_in_range",
-  "key_dimension_mismatch",
-  "empty_key_segment",
-  "invalid_period_format",
-  "invalid_period_range",
-  "structure_unavailable",
-  "dataflow_list_unavailable"
-]New value: +[
+  "dataflow_not_found",
+  "no_data",
+  "no_data_in_range",
+  "key_dimension_mismatch",
+  "empty_key_segment",
+  "invalid_period_format",
+  "invalid_period_range",
+  "structure_unavailable",
+  "canvas_unavailable",
+  "response_too_large",
+  "dataflow_list_unavailable"
+]

Previous value: -"Populated when a period bound was set but some observations carry a time_period label the range filter does not recognize — those rows are returned unfiltered, so the requested range did not apply to them."New value: +"Populated when a period bound was set but some observations carry a time_period label the range filter does not recognize. Composes with staged retrieval_guidance when both apply."

Previous value: -"Inline observations. Empty when results spilled to canvas (see canvas_id / table_name)."New value: +"Inline observation preview. For staged results this may contain the full set or a budget-limited prefix; observation_count remains the full count."

Added value: +{
+  "description": "Present on every staged result. Identifies the imf_dataframe_describe-before-imf_dataframe_query retrieval workflow.",
+  "type": "string"
+}

Added value: +{
+  "description": "True when the complete observation set is stored on DataCanvas. canvas_id and table_name are present whenever true.",
+  "type": "boolean"
+}

Previous value: -"DuckDB table name on the canvas — present when truncated=true; reference in SQL via FROM <table_name>."New value: +"DuckDB table name on the canvas — present when staged=true; reference in SQL via FROM <table_name>."

Previous value: -"True when the result exceeded the inline limit and was staged on a DataCanvas table; canvas_id and table_name are populated and imf_dataframe_query provides SQL access to the full set."New value: +"True only when observations is an incomplete preview of observation_count. A result can be staged=true and truncated=false when every observation also fits inline."

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dataflow_id",
+      "key",
+      "observations",
+      "series_attributes",
+      "observation_count",
+      "truncated",
+      "source"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `dataflow_not_found`: dataflow_id does not match any known dataflow on api.imf.org `no_data`: Key is structurally valid but the dataflow holds no series for this code combination, or the dataflow publishes no series at all `no_data_in_range`: The key returned observations but start_period/end_period excluded every one of them `key_dimension_mismatch`: Number of dot-separated segments in key does not match the dataflow's DSD dimension count `empty_key_segment`: A dot-separated position in key is empty or blank, which matches no series upstream `invalid_period_format`: start_period or end_period is not one of the recognized period formats `invalid_period_range`: start_period is later than end_period `structure_unavailable`: api.imf.org returns non-200 on the data endpoint `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD and data lookups are attempted Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "dataflow_not_found",
+            "no_data",
+            "no_data_in_range",
+            "key_dimension_mismatch",
+            "empty_key_segment",
+            "invalid_period_format",
+            "invalid_period_range",
+            "structure_unavailable",
+            "dataflow_list_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "dataflow_id",
-  "key",
-  "observations",
-  "series_attributes",
-  "observation_count",
-  "truncated",
-  "source"
-]

Previous value: -"Unit of measure, e.g. Percent, USD."New value: +"Unit of measure as the upstream code, e.g. PT (percent), USD, XDC (domestic currency), NUM (count). Null when the response carries no unit for the series — many dataflows publish none."

Previous value: -"Per-series attributes, one entry per distinct series_key in the result. Present only when the query resolved to more than one series; a single-series query carries its values in series_attributes instead. Scale differs across series in one query — WEO NGDPD is scale 9 while NGDP_RPCH is unscaled — so interpret each series against its own entry."New value: +"Per-series attributes, one entry per distinct series_key in the result. Present only when the query resolved to more than one series; a single-series query carries its values in series_attributes instead. Unit and scale differ across series in one query — WEO NGDPD is USD at scale 9 while NGDP_RPCH is PT unscaled — so interpret each series against its own entry."

Previous value: -"Unit of measure for this series, e.g. Percent."New value: +"Unit of measure for this series as the upstream code, e.g. PT (percent), USD, XDC (domestic currency). Null when the response carries none for it."

Previous value: -"Series-level attributes (unit, scale, decimals)."New value: +"Attributes of the first series in the result — the same series as series_metadata[0]. A key with + or * resolves to several series whose scale and unit differ, and this field describes only the first of them: read series_metadata for the rest, and never apply these values to another series_key."

Previous value: -"Scale multiplier, e.g. Billions."New value: +"Scale multiplier as the upstream code, e.g. 9 for billions. \"0\" means no multiplier — the values are unscaled."

Added value: +{
+  "description": "Per-series attributes, one entry per distinct series_key in the result. Present only when the query resolved to more than one series; a single-series query carries its values in series_attributes instead. Scale differs across series in one query — WEO NGDPD is scale 9 while NGDP_RPCH is unscaled — so interpret each series against its own entry.",
+  "items": {
+    "additionalProperties": false,
+    "description": "Unit, scale, and decimals for one series in the result.",
+    "properties": {
+      "decimals": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Number of decimal places shown for this series."
+      },
+      "scale": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Scale multiplier for this series as the upstream code, e.g. 9 for billions. \"0\" means no multiplier."
+      },
+      "series_key": {
+        "description": "Series these attributes belong to, matching observations[].series_key.",
+        "type": "string"
+      },
+      "unit": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Unit of measure for this series, e.g. Percent."
+      }
+    },
+    "required": [
+      "series_key",
+      "unit",
+      "scale",
+      "decimals"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Previous value: -"End of time range (inclusive). Same format as start_period, and must be greater than or equal to start_period. Observations after this period are excluded from the result."New value: +"End of time range (inclusive). Same formats as start_period, and must not be earlier than it. The bound covers the whole period it names, so end_period 2023 admits 2023-M12 and 2023-Q4. Observations after this period are excluded from the result."

Previous value: -"Dot-separated dimension codes in DSD keyPosition order. Call imf_get_database to get key_format and valid codes first. Use + to specify multiple codes (e.g. USA+GBR.NGDP_RPCH.A). Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."New value: +"Dot-separated dimension codes in DSD keyPosition order. Call imf_get_database to get key_format and valid codes first. Use + to combine codes at one position (e.g. USA+GBR.NGDP_RPCH.A). Use * to match every code at a position — *.NGDP_RPCH.A returns the indicator for all countries, and CAN.*.A every indicator for Canada. Every position needs a code or a *; an empty segment (USA..A) is rejected. Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."

Previous value: -"Start of time range (inclusive). Format matches the dataflow frequency: YYYY (annual), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly). Observations before this period are excluded from the result."New value: +"Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result."

Added value: +{
+  "description": "Populated when a period bound was set but some observations carry a time_period label the range filter does not recognize — those rows are returned unfiltered, so the requested range did not apply to them.",
+  "type": "string"
+}

Previous value: -"Time label as emitted by the upstream API. Annual: YYYY (e.g. 2023). Quarterly: YYYY-QN (e.g. 2023-Q1). Monthly: YYYY-MNN (e.g. 2023-M01, not YYYY-MM). start_period/end_period accept both YYYY-MM and YYYY-MNN for monthly comparisons."New value: +"Time label as emitted by the upstream API. Annual: YYYY (e.g. 2023). Semi-annual: YYYY-SN (e.g. 2023-S1). Quarterly: YYYY-QN (e.g. 2023-Q1). Monthly: YYYY-MNN (e.g. 2023-M01, not YYYY-MM). Daily: YYYY-MM-DD (e.g. 2023-01-05). Every one of these is also accepted as a start_period/end_period bound, so a label from this field can be passed straight back in."

Previous value: -"End of time range (inclusive). Same format as start_period. Observations after this period are excluded from the result."New value: +"End of time range (inclusive). Same format as start_period, and must be greater than or equal to start_period. Observations after this period are excluded from the result."

Previous value: -"Requested end of time range. Same format as start_period. See start_period note: the API returns the full series; this parameter is passed through but may not filter observations."New value: +"End of time range (inclusive). Same format as start_period. Observations after this period are excluded from the result."

Previous value: -"Requested start of time range. Format matches the dataflow frequency: YYYY (annual), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly). Note: the IMF SDMX 3.0 compact JSON endpoint returns the full available series regardless of this parameter — observations outside the requested range may still appear."New value: +"Start of time range (inclusive). Format matches the dataflow frequency: YYYY (annual), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly). Observations before this period are excluded from the result."

Previous value: -"Time label, e.g. 2023 or 2023-Q1 or 2023-01."New value: +"Time label as emitted by the upstream API. Annual: YYYY (e.g. 2023). Quarterly: YYYY-QN (e.g. 2023-Q1). Monthly: YYYY-MNN (e.g. 2023-M01, not YYYY-MM). start_period/end_period accept both YYYY-MM and YYYY-MNN for monthly comparisons."