{"uid":"cap_ojSRp5nr-exaQdZojilZ2","slug":"usgs-streamgage-instantaneous-values-with-historical-percentile-context-de01a96f","name":"USGS Streamgage Instantaneous Values with Historical Percentile Context","description":"Returns the latest instantaneous values at a USGS streamgage, together with what makes them readable. A stage of three point four feet means nothing on its own, so each value is placed against the station own record for the requested reference period: the minimum, median and maximum, and the percentile the current reading falls at. The reference period is stated with the comparison, because a percentile without a window is not a statistic.","url":"https://natur.halowerk.com/v1/river-gauge","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"site_id":{"type":"string","maxLength":20,"minLength":6,"description":"USGS site number, e.g. 01646500."},"reference_days":{"type":"integer","default":30,"maximum":365,"minimum":2,"description":"Window used to place the current reading in context."}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.004","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.004/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.004","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.004","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_ucfzCKzcZ0ukEldwFXajp","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.004","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the current instantaneous reading at a USGS streamgage station alongside historical context (min, median, max, and percentile) for a specified reference period.","exampleAgentPrompt":"What's the current stage at USGS streamgage 05420500 on the Mississippi River, and how does it compare to the historical record for the past 30 years — is it above or below normal right now?","exampleUseCases":[{"title":"Pre-trip river conditions check","prompt":"I'm planning a kayaking trip on the Niobrara River this weekend — can you check the current water level at USGS gauge 06465500 and tell me whether it's running high, low, or normal compared to the 10-year record for this time of year?"},{"title":"Flood risk situational awareness","prompt":"There's been heavy rain near Sacramento — what's the current stage reading at USGS gauge 11447650 on the Sacramento River, and what percentile does that put it at compared to the last 30 years of data?"},{"title":"Drought monitoring for watershed","prompt":"I need to know if the Colorado River at Lees Ferry (USGS gauge 09380000) is running unusually low — pull the latest discharge reading and show me where it falls against the historical minimum, median, and maximum for a 20-year reference period."}],"resultDescription":"Returns the latest instantaneous value (e.g. stage in feet or discharge in cfs) at the requested USGS streamgage, alongside the historical minimum, median, and maximum for the chosen reference period, plus the percentile at which the current reading falls. The reference period is explicitly labeled so the percentile is statistically interpretable.","failureModes":["Invalid or non-existent USGS station ID returns an error or empty result","Station is offline or has a data gap, returning no current value","Reference period too short or unavailable for the station's period of record","Network timeout fetching live USGS data","Parameter code not measured at requested station"],"whenToPreferThis":"Use this endpoint when you need not just the raw current streamgage reading but also its historical context — specifically the percentile rank against the station's own record for a defined window. Prefer this over a plain USGS API call when the user needs to interpret whether a level is unusual, flood-threatening, or drought-level, rather than just knowing the number.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:31:53.875Z","isFirstParty":false}