Fx Get Timeseries
fx_get_timeseriesGet historical daily Frankfurter v1 rates over an inclusive date range. Same-date EUR legs are divided without intermediate rounding; only days with both currencies appear, including observed self-pairs at 1 and historical retired currencies. Missing-leg served days produce coverage notices; weekends and holidays are not counted as missing. summary covers all observed days before delivery: arithmetic mean, earliest tied extrema, endpoints and percentage change, without accounting policy. limit bounds returned rows (default/max 500); 0 returns summary only. Continue inline with next_start_date, the same end_date and a positive limit. Long ranges (>90 days by default) stage beyond the 40,000-character preview budget, independently of limit. canvas_id, or stage: true on a new canvas, always stages the complete series, including short/empty results; either fails without DataCanvas, and an unknown canvas_id fails. Pass the returned canvas_id to stage another series beside it. Each registration preserves earlier tables with a unique table_name. spilled=true returns canvas_id and table_name; use fx_dataframe_describe then fx_dataframe_query for SQL. Without DataCanvas, omit canvas_id and stage to page inline.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"base_currency": "<base_currency>",
"quote_currency": "<quote_currency>",
"start_date": "<start_date>",
"end_date": "<end_date>"
},
"name": "fx_get_timeseries"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum observations returned in rates, default 500, clamped to 500. Use 0 for summary only; continue inline with a positive limit. Does not affect summary, counts, bounds, staging eligibility or the complete staged table. | |
| stage | No | true stages the complete series even when short or empty: on canvas_id when given, otherwise on a new canvas whose canvas_id is returned. To stage another series beside it, pass that canvas_id rather than stage: true again, since fx_dataframe_query reads one canvas at a time. false keeps automatic staging; canvas_id always stages. | |
| end_date | Yes | ISO 8601 end date (YYYY-MM-DD). Must be >= start_date. Future dates are not supported. | |
| canvas_id | No | Existing canvas ID from a prior call; stages the complete series on it even for short or empty results, whatever stage says. Every call creates a uniquely named table. Omit it and set stage: true to stage on a new canvas; omit both for automatic staging or inline paging. | |
| start_date | Yes | ISO 8601 start date (YYYY-MM-DD). Frankfurter v1 data starts 1999-01-04. The actual first data point is later when no rate was published on start_date (a weekend, a holiday, or a currency gap). | |
| base_currency | Yes | ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes. | |
| quote_currency | Yes | ISO 4217 quote currency code (e.g. EUR). Call fx_list_currencies to get valid codes. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| rates | No | Date → rate map in date order, observed days inside the requested range only. Bounded by limit (default/max 500), and by the character budget for automatically staged previews. Empty for limit 0 or no observations. Inline partial results continue with next_start_date and a positive limit; staged tables retain every observation. | |
| notice | No | Explains a result that would otherwise look broken or incomplete: an empty series (no publication day in the range); an inline page cut short (the start_date to continue from, plus why a long range was not staged when DataCanvas is turned off); or a spilled series (the canvas and table it was staged to, and the tools that read it). | |
| source | No | Always "Frankfurter v1" — the upstream data provider. | |
| spilled | No | True when the complete result was staged on DataCanvas, either explicitly through canvas_id or stage: true, or automatically after exceeding the threshold and preview budget. | |
| summary | No | Statistics over all observed days in the full clipped requested range before limit, paging or staging; omitted for empty ranges. Missing-leg coverage notices describe excluded served days. Continuations summarize their own requested interval. | |
| end_date | No | Last publication date in the requested range. Always inside the requested range — earlier than the requested end when that day had no Frankfurter v1 fix, and equal to it when the series is empty. Later than the last key in rates when truncated is true. | |
| canvas_id | No | Canvas ID — present when spilled is true. Pass to fx_dataframe_describe to inspect the staged table, then to fx_dataframe_query to run SQL. | |
| rate_type | No | Always "Daily rate (Frankfurter v1)" — these are reference rates, not tradeable bid/ask. | |
| truncated | No | True when rates holds only part of the series: an inline page (next_start_date continues it) or a spilled preview (spilled is true). False when rates holds every publication day in the requested range. | |
| rate_count | No | Total observed publication days in the requested range (the start_date through end_date passed on this call) — not the number of entries in rates, which is smaller when truncated is true. On a continuation call it counts the days from that start_date onward. | |
| start_date | No | First observed publication date in the requested range, including when limit is 0. Always inside the requested range — later than the requested start when that day had no Frankfurter v1 fix, and equal to it when the series is empty. | |
| table_name | No | Canvas table name — present when spilled is true. Use it as the FROM target in fx_dataframe_query SQL; fx_dataframe_describe lists its columns. | |
| base_currency | No | Base currency code. | |
| quote_currency | No | Quote currency code. | |
| next_start_date | No | Present only when an inline page was cut short: the first publication date not in rates. Pass it as start_date with the same end_date and a positive limit to get the next page. For limit 0 it is the first observation. Absent on the final page and staged results. |