Query the USGS Instantaneous Values (IV) service for real-time and recent surface-water and groundwater readings (streamflow, gage height, water temperature, etc). Data is available from 2007-10-01 onward.

Exactly one major filter is required to scope the query: sites, stateCd, huc, bBox, or countyCd. Providing zero, or more than one, is rejected. sites are USGS station numbers, typically 8 digits but 15 digits for many groundwater/well sites - pass them exactly as find_sites returns them, do not truncate or pad. Looking up a site by name (e.g. "Potomac River") is not supported by this tool; call find_sites first to resolve a name to a station number. bBox is an object {west, south, east, north} in decimal degrees - west/east are longitude (negative in the continental US), south/north are latitude (positive in the continental US) - with area (east-west)*(north-south) capped at 25 square degrees.

Date range: use either period (an ISO-8601 duration, e.g. P7D for the last 7 days) OR startDT/endDT for an absolute range - never both. endDT requires startDT. A query - dated or not - can return readings that are years old: a latest-value query returns the latest reading PER SENSOR, including sensors quietly gone dormant or decommissioned years ago, and a dated range can end early for one sensor while its siblings keep reporting through the end of the window. Every series carries stale, which is TRI-STATE, not a plain boolean: true (latest reading is more than 48 hours behind the query's reference time), false (it is not), or null (staleness could not be evaluated - no resolvable reference time, or no readings at all). Treat null as "not verified", never as current - check stale before reporting ANY value as current. discontinued explains WHY when USGS says so in the sensor's method description, but is not itself the signal to check - a sensor can go stale with no marker at all. When any returned series is stale or unevaluable, the response includes a note naming which ones, their reading dates, and how far behind they are.

This tool sends no siteStatus default, so USGS returns readings from ALL sites regardless of status - unlike find_sites, which defaults to siteStatus:"active". The same major filter can therefore return readings from sites find_sites didn't list. This is unrelated to stale/discontinued: a stale or decommissioned sensor sits at an otherwise-active site, so no siteStatus value filters it out.

Use mode:"summary" (not the default "values") for any window longer than a day. It returns {count, nonNullCount, min, max, mean, first, last} per series instead of every reading, avoiding truncation. mode:"values" returns up to maxValues (default 200, maximum 1000) of the MOST RECENT readings PER SERIES and sets truncated:true when more exist - a site with two sensors for the same parameter returns two series, each capped independently, so a 2-sensor site can still ship up to 2x maxValues readings total. checkResponseSize backstops the overall payload regardless. A single site over a single year already returns roughly 35,000 readings per series - windows beyond about a year should always use mode:"summary".

Returned values may be provisional (qualifier code "P") and subject to revision - present them as such, not as final measurements.

A series is omitted entirely, with no placeholder, when a site does not measure a requested parameter - a query for 3 parameterCd values can return fewer than 3 series. Match results on each series' variable.code; do not assume series[i] corresponds to parameterCd[i]. When this happens the result includes missingParameterCodes.

Don't know the 5-digit parameter code for what you want? Call list_common_parameter_codes first.

Look up the 5-digit USGS parameter code for a common measurement (e.g. streamflow, gage height, water temperature, dissolved oxygen) before calling get_instantaneous_values. Returns a static table of {code, name, unit, description}. No network call.

Look up USGS station numbers (siteNumber) to pass to get_instantaneous_values - use this whenever you have a place or river name ("what's the flow of the Chattahoochee in Atlanta") rather than a station number. Returned siteNumber values vary in length - typically 8 digits, but 15 for many groundwater/well sites - pass them through to get_instantaneous_values exactly as returned; do not truncate or pad.

Exactly one major filter is required: sites, stateCd, huc, bBox, or countyCd

• same rule and the same named {west, south, east, north} bBox object as get_instantaneous_values.

nameContains filters results CLIENT-SIDE after fetching, not on the request - the /site/ service silently ignores name-search parameters, so this NARROWS a major filter's results rather than replacing it, and cannot be used alone. Matching is case-insensitive (most USGS station names are uppercase, e.g. "CHATTAHOOCHEE RIVER AT ATLANTA, GA", but not all are), so match casually.

A broad major filter with no nameContains can return hundreds of sites - Georgia alone has 544 IV-reporting sites - so pair a broad filter (stateCd, a wide bBox) with nameContains when looking for a specific place, and prefer a narrower filter (countyCd, huc) otherwise.

Defaults to hasDataTypeCd:"iv" (only sites that report instantaneous values), since a site without IV data cannot be used with get_instantaneous_values. Also defaults to siteStatus:"active", unlike get_instantaneous_values (which sends no siteStatus default and so returns readings from ALL sites) - the same major filter can therefore list fewer sites here than get_instantaneous_values will actually return readings for. Pass siteStatus:"all" to see inactive/discontinued sites too. Results are capped at maxSites (default 50, maximum 500); when more match, truncated:true and totalMatched: show how many were found in total. The cap keeps the FIRST maxSites in USGS site-number order, which runs roughly by drainage basin - raising maxSites therefore returns a geographic slice, not a broader or more relevant sample. Narrow with nameContains or a tighter major filter instead of raising maxSites.