imf-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id'], 'properties': {'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Canvas ID returned by imf_query_dataset whenever staged=true, from automatic spillover or output_mode="canvas".'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['canvas_id', 'tables', 'table_count']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_not_found'], 'description': 'Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not match any registered DataCanvas session (expired, wrong session, or canvas disabled). Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'tables': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'row_count', 'columns'], 'properties': {'name': {'type': 'string', 'description': 'Table name â\x80\x94 use this in imf_dataframe_query SQL.'}, 'columns': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'type'], 'properties': {'name': {'type': 'string', 'description': 'Column name â\x80\x94 use this in SELECT and WHERE clauses.'}, 'type': {'type': 'string', 'description': 'DuckDB column type, e.g. VARCHAR, DOUBLE, BIGINT.'}}, 'description': 'A single column definition.', 'additionalProperties': False}, 'description': 'Column schema for this table.'}, 'row_count': {'type': 'number', 'description': 'Number of rows in this table.'}}, 'description': 'A single canvas table with its schema.', 'additionalProperties': False}, 'description': 'All tables registered on this canvas.'}, 'canvas_id': {'type': 'string', 'description': 'Canvas session ID that was introspected.'}, 'table_count': {'type': 'number', 'description': 'Total number of tables on the canvas.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id', 'sql'], 'properties': {'sql': {'type': 'string', 'description': "Read-only SQL SELECT statement â\x80\x94 exactly one statement, starting with SELECT or with a WITH â\x80¦ SELECT common table expression. Reference tables by the names returned by imf_dataframe_describe. Example: SELECT time_period, value FROM spilled_abc123 WHERE time_period >= '2010' ORDER BY time_period."}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Canvas ID returned by imf_query_dataset whenever staged=true. Call imf_dataframe_describe with it before writing SQL.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['rows', 'row_count', 'truncated']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'description': 'A result row â\x80\x94 keys are the selected column names, values match the column DuckDB types (string, number, null).', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Largest result-row prefix whose complete structured and formatted response fits the 100,000-character response budget, after the canvas row limit (default 10,000) is applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_not_found', 'missing_table', 'invalid_sql', 'sql_not_permitted', 'response_too_large'], 'description': 'Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not match any registered DataCanvas session (expired, wrong session, or canvas disabled). `missing_table`: The canvas exists but sql references a table that is not staged on it â\x80\x94 the table expired, was dropped, or the name is wrong. `invalid_sql`: sql is not a single SELECT statement (a leading WITH â\x80¦ SELECT counts as one), or it is SELECT-shaped but fails to prepare â\x80\x94 unknown column, unknown function, or a syntax error. `sql_not_permitted`: sql parses as a SELECT but the read-only gate refuses it â\x80\x94 it calls an external-data or PRAGMA table function, reads a system catalog, or plans an operator outside the read-only allowlist. `response_too_large`: The first result row cannot fit in the complete structured and formatted response budget. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'row_count': {'type': 'number', 'description': 'Number of materialized rows returned in rows. Always equals rows.length and never claims a pre-cap total.'}, 'truncated': {'type': 'boolean', 'description': 'True when DataCanvas capped the query at its row limit or the server omitted materialized rows to fit the response-size budget. Page the remainder with a stable ORDER BY plus LIMIT/OFFSET, or narrow the query with WHERE or aggregation.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['dataflow_id'], 'properties': {'limit': {'type': 'integer', 'maximum': 200, 'minimum': 1, 'description': 'Entries to return from the selected dimension. Valid only with dimension_id; default 50, maximum 200.'}, 'offset': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Matching entries to skip in the selected dimension before this page. Valid only with dimension_id; default 0.'}, 'version': {'type': 'string', 'description': 'Dataflow version, e.g. 9.0.0. Auto-detected from the dataflow list when omitted.'}, 'agency_id': {'type': 'string', 'description': 'Agency ID that publishes this dataflow, e.g. IMF.RES or IMF.STA. Auto-detected from the dataflow list when omitted.'}, 'dataflow_id': {'type': 'string', 'description': 'Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI.'}, 'dimension_id': {'type': 'string', 'minLength': 1, 'description': 'Exact dimension ID from this tool, e.g. INDICATOR. Select one dimension to page beyond its preview.'}, 'available_only': {'type': 'boolean', 'default': False, 'description': 'Return only codes reported by the dataflow-wide availability constraint. Default false keeps ordinary codelist discovery unchanged.'}, 'codelist_filter': {'type': 'string', 'minLength': 1, 'description': 'Optional words to search for in each dimension\'s codelist, split on spaces and commas. A code matches when every word appears, case-insensitively, in its code ID or name; different words may match different fields. Filtering runs before the 50-entry preview or selected-dimension page. Example: "CPI", "GDP constant prices", or "NGDP_RPCH percent" surfaces matching WEO indicator codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['dataflow_id', 'agency_id', 'version', 'name', 'key_format', 'truncated', 'dimensions', 'source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'name': {'type': 'string', 'description': 'Human-readable dataflow name.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['dataflow_not_found', 'dimension_not_found', 'structure_unavailable', 'dataflow_list_unavailable', 'availability_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `dataflow_not_found`: dataflow_id does not match any known dataflow on api.imf.org. `dimension_not_found`: dimension_id does not match a dimension in the selected dataflow. `structure_unavailable`: api.imf.org returns non-200 on the DSD endpoint. `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched â\x80\x94 fires before the DSD lookup is attempted. `availability_unavailable`: available_only is true and the dataflow-wide availability constraint cannot be fetched or parsed. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Populated when a codelist_filter matched no entries anywhere, or when a dimension has no resolvable codelist, or when offset is past the final match.'}, 'source': {'type': 'string', 'description': 'Attribution string required by IMF data terms: "Source: International Monetary Fund, <dataflow name>, <link>".'}, 'version': {'type': 'string', 'description': 'Dataflow version string, e.g. 9.0.0.'}, 'agency_id': {'type': 'string', 'description': 'Agency that publishes this dataflow, e.g. IMF.RES, IMF.STA.'}, 'truncated': {'type': 'boolean', 'description': 'True when any returned dimension page omits matching codes.'}, 'dimensions': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'position', 'codelist', 'codelist_truncated', 'unfiltered_count', 'matched_count', 'returned_count', 'offset'], 'properties': {'id': {'type': 'string', 'description': 'Dimension identifier used in the key, e.g. COUNTRY.'}, 'name': {'type': 'string', 'description': 'Human-readable dimension label from the DSD concept scheme, e.g. Weight Type for WGT_TYPE. Falls back to the dimension id when the structure names no concept.'}, 'offset': {'type': 'number', 'description': 'Matching codes skipped before this dimension page.'}, 'codelist': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name'], 'properties': {'id': {'type': 'string', 'description': 'Machine code for this dimension value, e.g. USA.'}, 'name': {'type': 'string', 'description': 'Human-readable label for this value, e.g. United States.'}}, 'description': 'A single codelist entry: machine code and human-readable name.', 'additionalProperties': False}, 'description': 'Valid codelist codes for this dimension, or codes reported with published data when available_only is true. Unselected previews show up to 50 entries after optional filtering. Select dimension_id and use limit/offset for a bounded page of up to 200 entries. Empty means the filter matched nothing when codelist_filter is echoed back, no coverage was reported in availability mode, or the codelist could not be resolved in normal mode â\x80\x94 see notice.'}, 'position': {'type': 'number', 'description': 'Zero-based position in the key string.'}, 'next_offset': {'type': 'number', 'description': 'Offset for the next page when later matching codes remain.'}, 'matched_count': {'type': 'number', 'description': 'Codes matching codelist_filter before limit and offset are applied.'}, 'returned_count': {'type': 'number', 'description': 'Codes returned in this dimension page.'}, 'available_count': {'type': 'number', 'description': 'Codes reported with published data before codelist_filter. Present when available_only is true.'}, 'unfiltered_count': {'type': 'number', 'description': 'Source codes before codelist_filter: the complete resolved codelist normally, or published codes when available_only is true.'}, 'codelist_truncated': {'type': 'boolean', 'description': 'True when matching codes were omitted before or after this page.'}}, 'description': 'A single dimension with its codelist or published availability coverage.', 'additionalProperties': False}, 'description': 'All dimension previews, or the one selected dimension page.'}, 'key_format': {'type': 'string', 'description': 'Dimension names in dot-separated keyPosition order, e.g. COUNTRY.INDICATOR.FREQUENCY. Use this exact format when constructing the key for imf_query_dataset.'}, 'dataflow_id': {'type': 'string', 'description': 'Dataflow identifier, e.g. WEO, BOP, CPI.'}, 'description': {'type': 'string', 'description': "This dataflow's own description in full â\x80\x94 not the shared DSD's, and not the shortened preview imf_list_databases returns for the same id. Absent when the dataflow publishes none."}, 'dsd_version': {'type': 'string', 'description': 'Version of the underlying data structure definition (DSD) that backs this dataflow. Differs from version when the dataflow references a shared DSD (e.g. IIP â\x86\x92 DSD_BOP at 24.0.0).'}, 'dimension_id': {'type': 'string', 'description': 'Selected dimension ID. Absent when previews for every dimension were returned.'}, 'series_count': {'type': 'number', 'description': 'Total series published by the dataflow. Present when available_only is true.'}, 'structure_ref': {'type': 'string', 'description': 'Identifier of the underlying DSD, e.g. DSD_BOP. Several dataflows can share one DSD.'}, 'available_only': {'type': 'boolean', 'const': True, 'description': 'True when dimensions contain published availability coverage rather than codelists.'}, 'codelist_filter': {'type': 'string', 'description': 'Echo of the codelist_filter that produced this result. Absent when no filter was applied â\x80\x94 an empty codelist then means the codelist could not be resolved, not that the filter missed.'}, 'time_period_end': {'type': ['string', 'null'], 'description': 'Latest period with published data, or null when the constraint omits it.'}, 'time_period_start': {'type': ['string', 'null'], 'description': 'Earliest period with published data, or null when the constraint omits it.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 200, 'minimum': 1, 'description': 'Maximum dataflows to return in this call. Default 50, ceiling 200; total_count reports how many matched, so a partial page is always recognizable as one.'}, 'filter': {'type': 'string', 'minLength': 1, 'description': 'Optional words to filter results by, split on spaces and commas. A dataflow matches when every word appears, case-insensitively, somewhere in its ID, name, or full description. Example: "exchange rate" returns ER and related dataflows; "WEO outlook" returns WEO and the regional outlooks built on it.'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Number of matching dataflows to skip before this page. Combine with limit to page through a broad or unfiltered catalog.'}, 'include_vintages': {'type': 'boolean', 'default': False, 'description': 'Include vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE. Default false â\x80\x94 vintages are excluded to keep the discovery surface clean.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['dataflows', 'total_count', 'returned_count', 'offset']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that bounded this page.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['dataflow_list_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `dataflow_list_unavailable`: The IMF SDMX structure endpoint that backs the dataflow catalog did not return a usable response. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Dataflows returned in this page.'}, 'notice': {'type': 'string', 'description': 'Populated when the filter matches nothing, or when matches remain beyond this page â\x80\x94 explains why and names the next offset to request.'}, 'offset': {'type': 'number', 'description': 'Number of matching dataflows skipped before this page.'}, 'dataflows': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'agency_id', 'version', 'name'], 'properties': {'id': {'type': 'string', 'description': 'Dataflow identifier, e.g. WEO, BOP, CPI.'}, 'name': {'type': 'string', 'description': 'Human-readable dataflow name.'}, 'version': {'type': 'string', 'description': 'Dataflow version, e.g. 9.0.0.'}, 'agency_id': {'type': 'string', 'description': 'Agency that publishes this dataflow, e.g. IMF.RES.'}, 'description': {'type': 'string', 'description': 'Short description, cut to 200 characters and ended with â\x80¦ when longer. imf_get_database and the imf://database/{dataflow_id} resource return the full text.'}}, 'description': 'A single IMF SDMX dataflow entry.', 'additionalProperties': False}, 'description': 'This page of matching dataflows; pass the id to imf_get_database to resolve dimension codelists.'}, 'truncated': {'type': 'boolean', 'description': 'True when matching dataflows remain beyond this page.'}, 'total_count': {'type': 'number', 'description': 'Dataflows matching filter and include_vintages, before limit and offset are applied. Exceeds returned_count when more pages remain.'}, 'returned_count': {'type': 'number', 'description': 'Dataflows in this page â\x80\x94 the length of dataflows.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['dataflow_id', 'key'], 'properties': {'key': {'type': 'string', 'description': "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 â\x80\x94 *.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. A * stands alone at its position â\x80\x94 combined with other codes (USA+*) it is rejected. Codes are trimmed and matched case-insensitively (usa resolves to USA), and the response echoes the canonical key. A code missing from its dimension's codelist is rejected before the query, naming the nearest valid codes. Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."}, 'version': {'type': 'string', 'description': 'Dataflow version. Auto-detected from dataflow list when omitted.'}, 'agency_id': {'type': 'string', 'description': 'Agency ID, e.g. IMF.RES or IMF.STA. Auto-detected from dataflow list when omitted.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': '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.'}, 'end_period': {'type': 'string', 'description': '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.'}, 'dataflow_id': {'type': 'string', 'description': 'Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. Matched case-insensitively; the response echoes the catalog spelling.'}, 'output_mode': {'enum': ['auto', 'canvas'], 'type': 'string', '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.'}, 'start_period': {'type': 'string', 'description': "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."}, 'last_n_observations': {'type': 'integer', 'maximum': 10000, 'minimum': 1, 'description': "Keep only each series' last N observations, an integer from 1 to 10,000; 1 returns each series' latest value. Latest is per series: series end at different periods, and a WEO series ends in its projection years (e.g. 2031), so set end_period to stop at a past year. With start_period or end_period, the last N inside that range. A series with fewer than N observations is returned whole. Omit to return every observation."}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['dataflow_id', 'key', 'observations', 'series_attributes', 'observation_count', 'staged', 'truncated', 'source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'key': {'type': 'string', 'description': 'Dimension key used in the query, trimmed and with each code in its codelist spelling, e.g. USA.NGDP_RPCH.A.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['dataflow_not_found', 'no_data', 'no_data_in_range', 'key_dimension_mismatch', 'empty_key_segment', 'wildcard_in_code_list', 'invalid_key_code', 'invalid_period_format', 'invalid_period_range', 'structure_unavailable', 'canvas_unavailable', 'response_too_large', 'dataflow_list_unavailable'], '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. `wildcard_in_code_list`: A key position combines * with other codes in a + list, where the portal ignores the * and returns only the listed codes. `invalid_key_code`: A key code is not in its dimension\'s codelist, checked before any data request. `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`: The fixed part of the result â\x80\x94 full series_metadata, plus the retrieval handle when staging â\x80\x94 exceeds the response budget before any observation can be included. `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched â\x80\x94 fires before the DSD and data lookups are attempted. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Populated when a period bound was set but some observations carry a time_period label the range filter does not recognize. Composes with retrieval_guidance, staged or not, when both apply.'}, 'source': {'type': 'string', 'description': 'Attribution string required by IMF data terms: "Source: International Monetary Fund, <dataflow name>, <link>".'}, 'staged': {'type': 'boolean', 'description': 'True when the complete observation set is stored on DataCanvas. canvas_id and table_name are present whenever true.'}, 'canvas_id': {'type': 'string', 'description': 'DataCanvas session ID â\x80\x94 present when staged=true. Pass first to imf_dataframe_describe, then to imf_dataframe_query.'}, 'truncated': {'type': 'boolean', 'description': '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, and staged=false and truncated=true when DataCanvas is not enabled and the full result exceeds the response budget.'}, 'end_period': {'type': 'string', 'description': 'Latest period covered; absent when the full available range was used.'}, 'table_name': {'type': 'string', 'description': 'DuckDB table name on the canvas â\x80\x94 present when staged=true; reference in SQL via FROM <table_name>.'}, 'dataflow_id': {'type': 'string', 'description': 'Dataflow identifier that was queried, in its catalog spelling, e.g. WEO.'}, 'observations': {'type': 'array', 'items': {'type': 'object', 'required': ['series_key', 'time_period', 'value', 'status'], 'properties': {'value': {'type': ['number', 'null'], 'description': "Observation value in base units, e.g. 29298025000000 for US GDP of $29.3 trillion; null when missing. The series' scale is already reflected in it: never apply scale to this value."}, 'status': {'type': ['string', 'null'], 'description': 'Observation status flag exactly as the dataflow publishes it, e.g. T, B, C, or NA; null when the observation carries none. The flags are not a shared vocabulary across dataflows. A null value with no status, or whose only status is the not-available marker NA or n.a. (any letter case), is omitted as padding; a null value with any other status is returned.'}, 'series_key': {'type': 'string', 'description': 'Dot-separated dimension codes identifying this series, e.g. USA.NGDP_RPCH.A. Matches the single-country equivalent of the query key â\x80\x94 useful when a query covers multiple countries.'}, 'time_period': {'type': 'string', 'description': '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.'}}, 'description': 'A single time-series observation.', 'additionalProperties': False}, 'description': 'Inline observations, oldest period first. When truncated=true this is the budget-limited time-ascending prefix of the result; observation_count remains the full count.'}, 'start_period': {'type': 'string', 'description': 'Earliest period covered; absent when the full available range was used.'}, 'series_metadata': {'type': 'array', 'items': {'type': 'object', 'required': ['series_key', 'unit', 'scale', 'decimals'], 'properties': {'unit': {'type': ['string', 'null'], 'description': '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.'}, 'scale': {'type': ['string', 'null'], 'description': 'Power of ten the IMF publishes this series in, as the upstream code: "9" is billions, "0" units. This series\' observation values are already in base units.'}, 'decimals': {'type': ['number', 'null'], 'description': 'Number of decimal places shown for this series.'}, 'series_key': {'type': 'string', 'description': 'Series these attributes belong to, matching observations[].series_key.'}}, 'description': 'Unit, scale, and decimals for one series in the result.', 'additionalProperties': False}, '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. Unit and scale differ across series in one query â\x80\x94 WEO NGDPD is USD published in billions (scale 9) while NGDP_RPCH is PT at scale 0 â\x80\x94 so interpret each series against its own entry.'}, 'observation_count': {'type': 'number', 'description': 'Total observations in the result, after any last_n_observations selection.'}, 'series_attributes': {'type': 'object', 'required': ['unit', 'scale', 'decimals'], 'properties': {'unit': {'type': ['string', 'null'], 'description': '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 â\x80\x94 many dataflows publish none.'}, 'scale': {'type': ['string', 'null'], 'description': 'Power of ten the IMF publishes this series in, as the upstream code: "9" is billions, "6" millions, "0" units. Observation values are already in base units, so the published figure is value / 10^scale.'}, 'decimals': {'type': ['number', 'null'], 'description': 'Number of decimal places shown.'}}, 'description': 'Attributes of the first series in the result â\x80\x94 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.', 'additionalProperties': False}, 'retrieval_guidance': {'type': 'string', 'description': 'Present on every staged result, where it names the imf_dataframe_describe-before-imf_dataframe_query retrieval workflow, and on a result truncated without DataCanvas, where it names the last time_period returned and how to narrow the query for the rest.'}, 'last_n_observations': {'type': 'number', 'description': "The last_n_observations input, echoed when set: observations holds each series' last N in the range. Absent when every observation was returned."}}, 'additionalProperties': False}