The REST API

Everything the site displays — 15-minute flow readings, statistics, comparisons, your tracked gages — is available programmatically under /api/v1/. This page teaches the API from zero; the machine-generated reference at /api/redoc/ documents every endpoint, and /api/docs/ lets you poke at them interactively.

Getting a key

Top-tier plans include programmatic API access. From the API console you can provision named API keys, reveal one again later, revoke it the moment you're done with it, and watch today's usage against your quota. A key carries exactly the access your account has — the gages you can read through the API are the gages you track on the site.

Authentication

Send the key as a Bearer token on every request:

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://gagelog.com/api/v1/sources/"

Two other credentials work everywhere a key does: short-lived JWT access tokens (POST /api/v1/auth/token/ with username + password on a verified account, refresh via /api/v1/auth/token/refresh/), and the browser session for same-origin calls. Prefer API keys for anything unattended — they're revocable individually and don't expire every five minutes.

First request: your gages

Reading endpoints serve the gages your account tracks. Start by listing them:

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://gagelog.com/api/v1/sources/"

[
  {"gage_key": "USGS", "display_name": "Dungeness River near Sequim, WA", ...},
  ...
]

If a gage you want is missing, track it on the site (or via POST /api/v1/sources/) first — GET /api/v1/sources/available/ shows what your plan can add.

Pulling readings

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://gagelog.com/api/v1/gauges/?gage_key=USGS&start=2026-07-01&end=2026-08-01"

Responses are paginated:

{
  "count": 2976,
  "next": "…&page=2",
  "previous": null,
  "results": [
    {"gage_key": "USGS", "timestamp": "2026-07-01T00:00:00Z",
     "cfs": 214.0, "flagged": false},
    ...
  ]
}

• page_size goes up to 5000 — fetch big ranges in few requests rather than day-by-day.
• Timestamps are UTC ISO-8601; flows are CFS.
• Exclude "flagged": true readings from any statistic — they're sensor errors (negative flows and the like), and the site's own analytics skip them too.

A complete Python example

import os, requests

BASE = "https://gagelog.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['GAGELOG_API_KEY']}"}

def readings(gage_key, start, end):
    rows, url = [], f"{BASE}/gauges/"
    params = {"gage_key": gage_key, "start": start, "end": end, "page_size": 5000}
    while url:
        resp = requests.get(url, headers=HEADERS, params=params, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        rows += [r for r in data["results"] if not r["flagged"]]
        url, params = data.get("next"), None   # "next" carries the query string
    return rows

july = readings("USGS", "2026-07-01", "2026-08-01")
print(f"{len(july)} readings, mean {sum(r['cfs'] for r in july)/len(july):.1f} cfs")

Endpoints at a glance

The full parameter-by-parameter reference lives at /api/redoc/.

Rate limits

API-key traffic has a generous daily quota plus a per-minute burst cap; GET /api/v1/developer/usage/ returns your numbers and today's count, and the console's Usage tab shows the same meter. Over the limit you get 429; the daily counter resets at midnight UTC. Browser sessions and access-token calls don't count against the quota.

Errors you'll meet

AI assistants

The console's AI integrations tab packages this whole page for machines: a downloadable Claude skill that teaches Claude to pull and analyze your flow data through your key, and Google Gemini Gem instructions that turn Gemini into a GageLog query-writer. Both know the endpoints, the pagination, the flagged-reading rule, and the water-year convention (Oct 1 – Sep 30, named for the ending year) so you don't have to re-explain them.