Register for a WattTime account and obtain an API token by POSTing credentials to the /login endpoint; the response contains a token field (JWT) valid for a limited period — store it securely and refresh it before expiry.
Identify the target grid region abbreviation using GET /region-from-loc?latitude={lat}&longitude={lon} or by consulting the WattTime region list; historical MOER data is keyed by region abbreviation (e.g., 'CAISO_NORTH').
Request historical MOER data via GET /historical with parameters: region={abbrev}, signal_type=co2_moer, start={ISO8601_datetime}, end={ISO8601_datetime}; the response is a JSON object with a 'data' array of {point_time, value, version} entries at five-minute resolution for most regions.
Paginate through large date ranges: if the requested range exceeds the maximum window allowed by your subscription tier, split the request into smaller sub-ranges (e.g., monthly chunks) and concatenate the results; check the response for a 'meta' object indicating truncation.
Store the data keyed by (region, point_time) and handle duplicate point_time entries caused by data revisions — WattTime occasionally reissues historical data with corrected values; use the 'version' field to identify the most recent revision.
For forecast data (used for carbon-aware scheduling), call GET /forecast with the same region and signal_type parameters — forecast data is a separate endpoint from historical and returns a probabilistic time series for the upcoming 24–72 hours depending on region.
Known gotchas
WattTime API v3 introduced expanded signal types (co2_moer, co2_aoer, health_damage) and new regional coverage; v2 endpoints are legacy and may be deprecated — use v3 endpoints and verify the signal_type parameter is explicitly set, as the default may differ between versions.
Historical data access depth and signal availability depend on subscription tier; the free tier provides only real-time and short-window historical access — bulk historical downloads require a commercial plan, and attempting to request data outside the allowed window returns a 403 or empty dataset without a clear error message.
MOER values are in lbs CO2 per MWh for US regions; international regions added in 2025 may use different units or have lower data quality — check the 'units' field in the response meta before performing emissions calculations.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp