Server definition
- Hash
- sha256:3d2466b9ec3f3634bcfe331112c36c1289604e84c97c643b07ca58b22a4e57fe
- What it is
- What a remote MCP server returned when asked what it offers: 5 tools
The blob, as servednamed by its sha256
{
"instructions": "IMF SDMX 3.0 macroeconomic data server. Keyless — no API key required.\nWorkflow: imf_list_databases → imf_get_database → imf_query_dataset\nCountry codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE).\nWith DataCanvas enabled (CANVAS_PROVIDER_TYPE=duckdb), large multi-country queries spill to it, and imf_query_dataset output_mode=\"canvas\" explicitly stages smaller results. For any staged result, call imf_dataframe_describe before imf_dataframe_query; when enabled, imf_dataframe_drop removes one completed table. Without DataCanvas, an over-budget result returns its earliest observations with truncated=true, and retrieval_guidance says how to narrow the query.\nKey legacy note: the IFS monolithic database is decomposed — use CPI, ER, IL, MFS_* instead.",
"tools": [
{
"description": "List DataCanvas tables and columns staged by a prior imf_query_dataset call. Returns each table's name, row count, and column schema (name + DuckDB type). Required before imf_dataframe_query to discover the table and column names for SQL.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Canvas ID returned by imf_query_dataset whenever staged=true, from automatic spillover or output_mode=\"canvas\".",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
}
},
"required": [
"canvas_id"
],
"type": "object"
},
"name": "imf_dataframe_describe",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"canvas_id",
"tables",
"table_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"canvas_id": {
"description": "Canvas session ID that was introspected.",
"type": "string"
},
"error": {
"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: `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.",
"examples": [
"canvas_not_found"
],
"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"
},
"table_count": {
"description": "Total number of tables on the canvas.",
"type": "number"
},
"tables": {
"description": "All tables registered on this canvas.",
"items": {
"additionalProperties": false,
"description": "A single canvas table with its schema.",
"properties": {
"columns": {
"description": "Column schema for this table.",
"items": {
"additionalProperties": false,
"description": "A single column definition.",
"properties": {
"name": {
"description": "Column name — use this in SELECT and WHERE clauses.",
"type": "string"
},
"type": {
"description": "DuckDB column type, e.g. VARCHAR, DOUBLE, BIGINT.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"name": {
"description": "Table name — use this in imf_dataframe_query SQL.",
"type": "string"
},
"row_count": {
"description": "Number of rows in this table.",
"type": "number"
}
},
"required": [
"name",
"row_count",
"columns"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Run a read-only SQL SELECT against a DataCanvas table staged by imf_query_dataset. Supports multi-country comparisons, time-series aggregation, and cross-indicator joins. Requires imf_dataframe_describe first to discover table and column names. One SELECT statement per call; a leading WITH … SELECT (CTE) is accepted. DML and DDL are rejected.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Canvas ID returned by imf_query_dataset whenever staged=true. Call imf_dataframe_describe with it before writing SQL.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"sql": {
"description": "Read-only SQL SELECT statement — exactly one statement, starting with SELECT or with a WITH … 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.",
"type": "string"
}
},
"required": [
"canvas_id",
"sql"
],
"type": "object"
},
"name": "imf_dataframe_query",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rows",
"row_count",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"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: `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 — the table expired, was dropped, or the name is wrong. `invalid_sql`: sql is not a single SELECT statement (a leading WITH … SELECT counts as one), or it is SELECT-shaped but fails to prepare — unknown column, unknown function, or a syntax error. `sql_not_permitted`: sql parses as a SELECT but the read-only gate refuses it — 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.",
"examples": [
"canvas_not_found",
"missing_table",
"invalid_sql",
"sql_not_permitted",
"response_too_large"
],
"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"
},
"row_count": {
"description": "Number of materialized rows returned in rows. Always equals rows.length and never claims a pre-cap total.",
"type": "number"
},
"rows": {
"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.",
"items": {
"additionalProperties": {},
"description": "A result row — keys are the selected column names, values match the column DuckDB types (string, number, null).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"type": "array"
},
"truncated": {
"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.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Fetch a dataflow's dimension list with a codelist preview for each dimension. Resolves human-readable terms to SDMX codes (e.g. \"United States\" → USA, \"Constant prices\" → NGDP_RPCH). Required before imf_query_dataset — SDMX keys are opaque without codelist lookups. Each codelist is capped at the first 50 entries by default, including previews filtered by codelist_filter. Set dimension_id to retrieve one codelist with bounded limit/offset paging after the optional codelist_filter, which keeps codes whose ID or name contains every word given. Set available_only=true to page codes the dataflow actually publishes, with series and time coverage metadata; availability filtering happens before codelist_filter and paging. The imf://database/{dataflow_id} resource provides the same bounded discovery summary. Country codes are ISO 3-letter (USA, GBR, DEU), not ISO 2-letter (US, GB, DE). The key_format field shows the exact dimension order required by imf_query_dataset. Note: codelists enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series in this dataflow.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"agency_id": {
"description": "Agency ID that publishes this dataflow, e.g. IMF.RES or IMF.STA. Auto-detected from the dataflow list when omitted.",
"type": "string"
},
"available_only": {
"default": false,
"description": "Return only codes reported by the dataflow-wide availability constraint. Default false keeps ordinary codelist discovery unchanged.",
"type": "boolean"
},
"codelist_filter": {
"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.",
"minLength": 1,
"type": "string"
},
"dataflow_id": {
"description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI.",
"type": "string"
},
"dimension_id": {
"description": "Exact dimension ID from this tool, e.g. INDICATOR. Select one dimension to page beyond its preview.",
"minLength": 1,
"type": "string"
},
"limit": {
"description": "Entries to return from the selected dimension. Valid only with dimension_id; default 50, maximum 200.",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"offset": {
"description": "Matching entries to skip in the selected dimension before this page. Valid only with dimension_id; default 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"version": {
"description": "Dataflow version, e.g. 9.0.0. Auto-detected from the dataflow list when omitted.",
"type": "string"
}
},
"required": [
"dataflow_id"
],
"type": "object"
},
"name": "imf_get_database",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflow_id",
"agency_id",
"version",
"name",
"key_format",
"truncated",
"dimensions",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"agency_id": {
"description": "Agency that publishes this dataflow, e.g. IMF.RES, IMF.STA.",
"type": "string"
},
"available_only": {
"const": true,
"description": "True when dimensions contain published availability coverage rather than codelists.",
"type": "boolean"
},
"codelist_filter": {
"description": "Echo of the codelist_filter that produced this result. Absent when no filter was applied — an empty codelist then means the codelist could not be resolved, not that the filter missed.",
"type": "string"
},
"dataflow_id": {
"description": "Dataflow identifier, e.g. WEO, BOP, CPI.",
"type": "string"
},
"description": {
"description": "This dataflow's own description in full — not the shared DSD's, and not the shortened preview imf_list_databases returns for the same id. Absent when the dataflow publishes none.",
"type": "string"
},
"dimension_id": {
"description": "Selected dimension ID. Absent when previews for every dimension were returned.",
"type": "string"
},
"dimensions": {
"description": "All dimension previews, or the one selected dimension page.",
"items": {
"additionalProperties": false,
"description": "A single dimension with its codelist or published availability coverage.",
"properties": {
"available_count": {
"description": "Codes reported with published data before codelist_filter. Present when available_only is true.",
"type": "number"
},
"codelist": {
"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 — see notice.",
"items": {
"additionalProperties": false,
"description": "A single codelist entry: machine code and human-readable name.",
"properties": {
"id": {
"description": "Machine code for this dimension value, e.g. USA.",
"type": "string"
},
"name": {
"description": "Human-readable label for this value, e.g. United States.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"codelist_truncated": {
"description": "True when matching codes were omitted before or after this page.",
"type": "boolean"
},
"id": {
"description": "Dimension identifier used in the key, e.g. COUNTRY.",
"type": "string"
},
"matched_count": {
"description": "Codes matching codelist_filter before limit and offset are applied.",
"type": "number"
},
"name": {
"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.",
"type": "string"
},
"next_offset": {
"description": "Offset for the next page when later matching codes remain.",
"type": "number"
},
"offset": {
"description": "Matching codes skipped before this dimension page.",
"type": "number"
},
"position": {
"description": "Zero-based position in the key string.",
"type": "number"
},
"returned_count": {
"description": "Codes returned in this dimension page.",
"type": "number"
},
"unfiltered_count": {
"description": "Source codes before codelist_filter: the complete resolved codelist normally, or published codes when available_only is true.",
"type": "number"
}
},
"required": [
"id",
"name",
"position",
"codelist",
"codelist_truncated",
"unfiltered_count",
"matched_count",
"returned_count",
"offset"
],
"type": "object"
},
"type": "array"
},
"dsd_version": {
"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 → DSD_BOP at 24.0.0).",
"type": "string"
},
"error": {
"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. `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 — 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.",
"examples": [
"dataflow_not_found",
"dimension_not_found",
"structure_unavailable",
"dataflow_list_unavailable",
"availability_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"
},
"key_format": {
"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.",
"type": "string"
},
"name": {
"description": "Human-readable dataflow name.",
"type": "string"
},
"notice": {
"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.",
"type": "string"
},
"series_count": {
"description": "Total series published by the dataflow. Present when available_only is true.",
"type": "number"
},
"source": {
"description": "Attribution string required by IMF data terms: \"Source: International Monetary Fund, <dataflow name>, <link>\".",
"type": "string"
},
"structure_ref": {
"description": "Identifier of the underlying DSD, e.g. DSD_BOP. Several dataflows can share one DSD.",
"type": "string"
},
"time_period_end": {
"description": "Latest period with published data, or null when the constraint omits it.",
"type": [
"string",
"null"
]
},
"time_period_start": {
"description": "Earliest period with published data, or null when the constraint omits it.",
"type": [
"string",
"null"
]
},
"truncated": {
"description": "True when any returned dimension page omits matching codes.",
"type": "boolean"
},
"version": {
"description": "Dataflow version string, e.g. 9.0.0.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "List IMF SDMX dataflows available on the portal. Entry point for every query: imf_get_database and imf_query_dataset both require a dataflow id obtained here. Vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE are excluded by default; set include_vintages=true to include them. Results are paged — 50 per call by default, adjustable with limit and offset — and total_count reports how many dataflows matched. Descriptions are shortened here; imf_get_database returns the full text for a single dataflow.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"filter": {
"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.",
"minLength": 1,
"type": "string"
},
"include_vintages": {
"default": false,
"description": "Include vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE. Default false — vintages are excluded to keep the discovery surface clean.",
"type": "boolean"
},
"limit": {
"default": 50,
"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.",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Number of matching dataflows to skip before this page. Combine with limit to page through a broad or unfiltered catalog.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"name": "imf_list_databases",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflows",
"total_count",
"returned_count",
"offset"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that bounded this page.",
"type": "number"
},
"dataflows": {
"description": "This page of matching dataflows; pass the id to imf_get_database to resolve dimension codelists.",
"items": {
"additionalProperties": false,
"description": "A single IMF SDMX dataflow entry.",
"properties": {
"agency_id": {
"description": "Agency that publishes this dataflow, e.g. IMF.RES.",
"type": "string"
},
"description": {
"description": "Short description, cut to 200 characters and ended with … when longer. imf_get_database and the imf://database/{dataflow_id} resource return the full text.",
"type": "string"
},
"id": {
"description": "Dataflow identifier, e.g. WEO, BOP, CPI.",
"type": "string"
},
"name": {
"description": "Human-readable dataflow name.",
"type": "string"
},
"version": {
"description": "Dataflow version, e.g. 9.0.0.",
"type": "string"
}
},
"required": [
"id",
"agency_id",
"version",
"name"
],
"type": "object"
},
"type": "array"
},
"error": {
"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_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.",
"examples": [
"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"
},
"notice": {
"description": "Populated when the filter matches nothing, or when matches remain beyond this page — explains why and names the next offset to request.",
"type": "string"
},
"offset": {
"description": "Number of matching dataflows skipped before this page.",
"type": "number"
},
"returned_count": {
"description": "Dataflows in this page — the length of dataflows.",
"type": "number"
},
"shown": {
"description": "Dataflows returned in this page.",
"type": "number"
},
"total_count": {
"description": "Dataflows matching filter and include_vintages, before limit and offset are applied. Exceeds returned_count when more pages remain.",
"type": "number"
},
"truncated": {
"description": "True when matching dataflows remain beyond this page.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Query an IMF SDMX dataflow by dimension key over a time range. Returns observations with time_period, value, and status, plus the unit, scale, and decimals of each series — a key resolving to several series carries one entry per series in series_metadata, since unit and scale differ between them. Requires imf_get_database first to obtain the correct key_format and valid dimension codes. Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE). Key format: dot-separated codes in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO). Every position must carry a code: use + to combine codes (e.g. USA+GBR.NGDP_RPCH.A) and * to match every code at a position (e.g. *.NGDP_RPCH.A for all countries); * stands alone and cannot join a + list. Codes are matched case-insensitively and checked against each dimension's codelist before the query — an unknown code is rejected with the nearest valid codes. Codelists from imf_get_database enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series. start_period and end_period must be valid period strings (YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD) with start_period no later than end_period; malformed or reversed ranges are rejected. A bound covers the whole period it names, so end_period 2023 includes 2023-M12 and 2023-Q4. last_n_observations keeps each series' last N observations — 1 is each series' latest value, the cheap way to ask many countries for their latest figure. Values are in base units everywhere, staged canvas rows included: scale is the power of ten the IMF publishes a series in (value / 10^scale is the published figure), never a factor still to apply. A response is held to 100,000 serialized characters. With DataCanvas enabled (CANVAS_PROVIDER_TYPE=duckdb), a larger result (multi-country, long time range) spills to it: call imf_dataframe_describe first to inspect staged tables and columns, then imf_dataframe_query for SQL analysis. Without DataCanvas, a larger result returns its earliest observations with truncated=true, and retrieval_guidance names the last period returned and how to narrow the query.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"agency_id": {
"description": "Agency ID, e.g. IMF.RES or IMF.STA. Auto-detected from dataflow list when omitted.",
"type": "string"
},
"canvas_id": {
"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.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"dataflow_id": {
"description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. Matched case-insensitively; the response echoes the catalog spelling.",
"type": "string"
},
"end_period": {
"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.",
"type": "string"
},
"key": {
"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 — *.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 — 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.",
"type": "string"
},
"last_n_observations": {
"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.",
"maximum": 10000,
"minimum": 1,
"type": "integer"
},
"output_mode": {
"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"
},
"start_period": {
"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.",
"type": "string"
},
"version": {
"description": "Dataflow version. Auto-detected from dataflow list when omitted.",
"type": "string"
}
},
"required": [
"dataflow_id",
"key"
],
"type": "object"
},
"name": "imf_query_dataset",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflow_id",
"key",
"observations",
"series_attributes",
"observation_count",
"staged",
"truncated",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"canvas_id": {
"description": "DataCanvas session ID — present when staged=true. Pass first to imf_dataframe_describe, then to imf_dataframe_query.",
"type": "string"
},
"dataflow_id": {
"description": "Dataflow identifier that was queried, in its catalog spelling, e.g. WEO.",
"type": "string"
},
"end_period": {
"description": "Latest period covered; absent when the full available range was used.",
"type": "string"
},
"error": {
"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. `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 — full series_metadata, plus the retrieval handle when staging — 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 — 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",
"wildcard_in_code_list",
"invalid_key_code",
"invalid_period_format",
"invalid_period_range",
"structure_unavailable",
"canvas_unavailable",
"response_too_large",
"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"
},
"key": {
"description": "Dimension key used in the query, trimmed and with each code in its codelist spelling, e.g. USA.NGDP_RPCH.A.",
"type": "string"
},
"last_n_observations": {
"description": "The last_n_observations input, echoed when set: observations holds each series' last N in the range. Absent when every observation was returned.",
"type": "number"
},
"notice": {
"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.",
"type": "string"
},
"observation_count": {
"description": "Total observations in the result, after any last_n_observations selection.",
"type": "number"
},
"observations": {
"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.",
"items": {
"additionalProperties": false,
"description": "A single time-series observation.",
"properties": {
"series_key": {
"description": "Dot-separated dimension codes identifying this series, e.g. USA.NGDP_RPCH.A. Matches the single-country equivalent of the query key — useful when a query covers multiple countries.",
"type": "string"
},
"status": {
"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.",
"type": [
"string",
"null"
]
},
"time_period": {
"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.",
"type": "string"
},
"value": {
"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.",
"type": [
"number",
"null"
]
}
},
"required": [
"series_key",
"time_period",
"value",
"status"
],
"type": "object"
},
"type": "array"
},
"retrieval_guidance": {
"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.",
"type": "string"
},
"series_attributes": {
"additionalProperties": false,
"description": "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.",
"properties": {
"decimals": {
"description": "Number of decimal places shown.",
"type": [
"number",
"null"
]
},
"scale": {
"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.",
"type": [
"string",
"null"
]
},
"unit": {
"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 — many dataflows publish none.",
"type": [
"string",
"null"
]
}
},
"required": [
"unit",
"scale",
"decimals"
],
"type": "object"
},
"series_metadata": {
"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 — WEO NGDPD is USD published in billions (scale 9) while NGDP_RPCH is PT at scale 0 — so interpret each series against its own entry.",
"items": {
"additionalProperties": false,
"description": "Unit, scale, and decimals for one series in the result.",
"properties": {
"decimals": {
"description": "Number of decimal places shown for this series.",
"type": [
"number",
"null"
]
},
"scale": {
"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.",
"type": [
"string",
"null"
]
},
"series_key": {
"description": "Series these attributes belong to, matching observations[].series_key.",
"type": "string"
},
"unit": {
"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.",
"type": [
"string",
"null"
]
}
},
"required": [
"series_key",
"unit",
"scale",
"decimals"
],
"type": "object"
},
"type": "array"
},
"source": {
"description": "Attribution string required by IMF data terms: \"Source: International Monetary Fund, <dataflow name>, <link>\".",
"type": "string"
},
"staged": {
"description": "True when the complete observation set is stored on DataCanvas. canvas_id and table_name are present whenever true.",
"type": "boolean"
},
"start_period": {
"description": "Earliest period covered; absent when the full available range was used.",
"type": "string"
},
"table_name": {
"description": "DuckDB table name on the canvas — present when staged=true; reference in SQL via FROM <table_name>.",
"type": "string"
},
"truncated": {
"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.",
"type": "boolean"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:3d2466b9ec3f3634bcfe331112c36c1289604e84c97c643b07ca58b22a4e57fe | sha256sum