# USGS Streamgage Instantaneous Values with Historical Percentile Context

> USGS Streamgage Instantaneous Values with Historical Percentile Context is a paid API for AI agents from natur.halowerk.com, paid per call via x402, $0.004/call, status unknown (last checked 2026-09-14).

Returns the current instantaneous reading at a USGS streamgage station alongside historical context (min, median, max, and percentile) for a specified reference period.

## Facts

- Endpoint: POST https://natur.halowerk.com/v1/river-gauge
- Price: $0.004/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/usgs-streamgage-instantaneous-values-with-historical-percentile-context-de01a96f
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_ojSRp5nr-exaQdZojilZ2

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability usgs-streamgage-instantaneous-values-with-historical-percentile-context-de01a96f -d '<json body>'
```

Example prompt: 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?

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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."
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/usgs-streamgage-instantaneous-values-with-historical-percentile-context-de01a96f/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from natur.halowerk.com](https://www.zero.xyz/host/natur.halowerk.com/llms.txt)