Water Get Series
water_get_seriesRead-onlyIdempotent
Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. Large sets (>500 records) return the most recent records inline with truncated=true — the last 500 without DataCanvas, and with DataCanvas enabled the complete series also spills to a canvas (canvas_id/table_name): inspect the staged table with water_dataframe_describe, then read the full series with water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | USGS site number (8–15 digits, e.g. "01646500" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers. | |
| endDate | Yes | End date in YYYY-MM-DD format (e.g. "2024-12-31"). | |
| canvas_id | No | Canvas ID from a prior call to add this series as a table on an existing canvas rather than creating a new one. Each distinct site, parameter code, series type, and date range gets its own table name, so re-running the identical query replaces its own table while a different query adds another alongside it. Applies only when the series spills to a canvas. Omit to start a fresh canvas. | |
| startDate | Yes | Start date in YYYY-MM-DD format (e.g. "2024-01-01"). | |
| seriesType | No | "daily" returns one value per day (DV service, typically mean/max/min). "instantaneous" returns ~15-minute readings (IV service). Default: "daily". Use "instantaneous" for high-resolution analysis. | daily |
| parameterCd | Yes | A single 5-digit USGS parameter code (e.g. "00060" for discharge, "00065" for gage height). One code per call — this tool returns one series. Use water_list_parameters to discover available codes. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| query | No | Query parameters used for this request. | |
| notice | No | Advisory about this result: the staged canvas table and how to read it, the advice to narrow the date range when the series was truncated with no canvas available, or the fact that a supplied canvas_id went unused because nothing was staged. | |
| values | No | Time-ordered value records, oldest first within the slice. Holds every record when truncated is false; when truncated, the most recent records only — the last 500 without DataCanvas, or the last N that fit the inline preview budget when the full series is staged on a canvas. | |
| siteName | No | Human-readable USGS site name. | |
| unitCode | No | Unit of measure for all values in this series (e.g. "ft3/s", "ft"). | |
| canvas_id | No | Canvas ID for the DataCanvas holding the full time series. Present only when truncated=true and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query. | |
| truncated | No | True when the result exceeds 500 records and only the most recent were returned inline. When canvas_id is present, inspect the staged table with water_dataframe_describe then read the full series with water_dataframe_query; otherwise narrow the date range. | |
| seriesType | No | "daily" = one value per day (DV service); "instantaneous" = ~15-minute readings (IV service). | |
| siteNumber | No | USGS site number (8–15 digits, e.g. "01646500"). | |
| table_name | No | DuckDB table name in the canvas holding all records. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL. | |
| parameterCd | No | 5-digit USGS parameter code (e.g. "00060" for discharge). | |
| totalRecords | No | Total number of records in the upstream result set (before any truncation). | |
| parameterName | No | Human-readable parameter name with units (e.g. "Streamflow, ft³/s"). |