Time-of-Use API FAQ's

No. Free is $0, 3 locations, 500 calls/month, no card. Enough for a weekend project if you refresh at next_change_at instead of polling.

Free, if you follow the recipe: refresh at next_change_at instead of polling. That's a handful of calls per day and one ZIP — well inside 500 calls and 3 locations. A 15-minute poll is ~2,880 calls/month and will exhaust Free. Recipe: /docs/#home-assistant.

Builder, on webhooks. 50 sites fit the 100-location cap. One webhook endpoint can watch every location on the plan, and deliveries do not count as API calls. Polling those 50 sites every 15 minutes is ~144,000 calls/month and needs Growth. Landing page: /ev-charging/.

Free is 1 seat. Builder is 3, Growth is 5, Business is 15, Enterprise is unlimited. Roles are owner, admin, and member. Everyone in the org shares one quota pool — seats are people, not extra locations or calls.

Yes. Upgrades take effect immediately and we prorate the difference. Downgrades apply at the start of your next billing cycle so you don't lose paid-for capacity.

Annual billing is available on Growth and above — contact us for a quote. Enterprise agreements are always annual.

A unique location is any distinct ZIP code or address you've queried in the current billing period. Querying 94103 ten times in one day still counts as one location. Street addresses in the same ZIP still count as that ZIP. Locations reset at the start of each billing cycle.

Once you hit the call or location cap, further new usage returns 429 Too Many Requests. We don't auto-bill overages or silently degrade. Free accounts get one email at 80% of the call cap per cycle. We don't send a 100% email, on any plan. Paid plans see the 429 (with an upgrade hint) and no quota emails. Upgrade and the next call goes through.

No. A 403 is a plan gate — for example an over-horizon forward request — not a usage cap. Rejected calls (400, 401, 403, 404, 422, 429) still appear in the request log, but only 2xx responses debit the call meter.

Yes — every MCP tool invocation counts as one API call against the same key and monthly quota as REST. Locations are deduplicated the same way. A chatty agent loop can burn the Free 500-call cap in a single session.

Every REST and MCP call shows up in the dashboard request log as a paginated list (20 per page): timestamp, endpoint, source, status code, and duration. It does not include the location queried, the request or response body, search, or CSV/JSON export. Plans differ only in how far back the log reaches — 24 hours on Free up to 90 days on Business.

On every paid plan, we POST to your server whenever a TOU period changes for a location you're watching — so you can react to peak/off-peak transitions without polling. An endpoint is a destination URL that receives those events; the limit is the number of distinct URLs you can register: 3 on Builder, 10 on Growth, 25 on Business, and unlimited on Enterprise. The limit is on endpoints only — each one can cover any of the locations included in your plan, so you don't pick a separate webhook quota. Webhooks aren't available on the Free plan. Product page: /webhooks/.

No. Server-side watches and the POSTs to your endpoints do not debit the call meter. Watched ZIPs still count as unique locations, and you still have an endpoint-URL cap. That's why a 50-site fleet fits Builder on webhooks but not on a 15-minute poll.

Pass a ZIP and we never call Geocodio. Pass street, city, or state and we geocode on a cache miss; that consumes one geocode from a separate per-cycle cap: 25 on Free, 250 on Builder, 1,500 on Growth, 7,500 on Business, unlimited on Enterprise. Cached addresses are free. ZIP-only queries never consume a geocode. Hitting the cap returns 429 (geocode_quota_exceeded) — we don't bill an overage.

Utility territories don't follow ZIP lines. unique — one utility. ambiguous — the ZIP overlaps more than one; every candidate is in results. no_coverage — none mapped. Pass street (plus city / state) to geocode and narrow to the territory that contains the point. If geocoding fails, the full ambiguous result is returned — coverage is never dropped silently. Docs: /docs/#resolution.

results is every active TOU plan for that ZIP and customer_class. We don't know which tariff the meter is enrolled on — that's on the bill. Pick the plan the site actually uses, or present the list. A ZIP can have several residential TOU options at once.

No. tou.tools returns TOU-specific data only — period names, period boundaries, and schedules. Actual rate values vary by tariff rider, customer class, and baseline allowance, which are out of scope. If you need dollar amounts, look them up against your own bill or your utility's published schedule.

Every period is one of off_peak, mid_peak, on_peak, super_off_peak, or critical_peak. off_peak is the implicit default when no schedule rule matches. Not every tariff uses every name — many are peak / off-peak only. Docs: /docs/#periods.

When the tariff publishes them, period is critical_peak. Webhooks fire on that transition the same as any other boundary. Those windows are declared on a limited number of days and can land with little notice — the Accuracy Guarantee's 14-day grace still applies. Docs: /docs/#periods.

GET /query/forward — and a future at on /query/current — is gated by your plan's forward schedule horizon. Free is current period only. Builder is 24 hours, Growth 7 days, Business 30 days, Enterprise custom. Ask for more than that and the call returns 403 (horizon_exceeded) with an upgrade hint — the window is never silently clamped. Docs: /docs/#forward.

No. customer_class is a query parameter on every plan, including Free: residential (default), commercial, industrial, agricultural, ev. It selects which rate plan we return for that ZIP, not a paid add-on.

Utilities file tariff revisions on their own schedule, and new rules sometimes take effect within days of being filed. To leave room for us to detect and incorporate the change, the Accuracy Guarantee has a 14-day grace window: responses served within 14 days of a tariff revision's effective date aren't covered. The guarantee resumes for queries dated after the window. The effective date — not the filing date or the date we learned of the change — governs. See terms section 5.3.

Yes. GET /query/forward returns a concrete period timeline with start/end timestamps, out to your plan's horizon: 24 hours on Builder, 7 days on Growth, 30 days on Business. Free is current period only. Pair it with webhooks so dispatch reacts when the period actually flips. We still don't return $/kWh — your value model stays yours. /battery/ is the dispatch landing page. Docs: /docs/#forward.

Yes. GET /query/current with the site ZIP (customer_class=ev or commercial) and rate_plan_id pinned to the schedule on the bill. Pause stalls when period is on_peak or critical_peak; resume on off_peak or super_off_peak. Paid plans add GET /query/forward for overnight windows and webhooks for the flip. We still don't return $/kWh or kW demand charges. /ev-charging/ is the fleet landing page.

Call GET /query/current with the house ZIP and rate_plan_id from a Home Assistant REST sensor. Pin the plan on your bill — a ZIP often has several. results[0].period is then the live period (off_peak, on_peak, and others). Automate on that sensor, or on a binary sensor that is on during off-peak and super-off-peak. /home-assistant/ is the landing page. Recipe: /docs/#home-assistant.

Yes. On a state change of sensor.tou_period, call select.select_option on your utility_meter tariff selector. Map off_peak / super_off_peak to your cheap tariff name, on_peak to peak. Pair with an energy monitor or power monitor for kWh — this API is the clock. /home-assistant/ is the landing page. Recipe: /docs/#home-assistant.

Don't. That's ~2,880 calls per device per month and will exhaust Free (500) — at fleet scale it chews through Builder (25,000) too. Resolve the utility at install (pass a street address if the ZIP is ambiguous), then refresh at next_change_at, or use webhooks on a paid plan. Unique locations equal installed units, not polls.

Pass customer_class=commercial or industrial. Each distinct ZIP is one unique location — about 2,000 sites fit Business. Watch them with webhooks instead of a 15-minute poll. We tell you when on-peak is; we don't compute kW demand charges.

Pass customer_class=agricultural. Ag clocks are often seasonal and different hours than the residential plan on the same ZIP — the default residential class is the wrong table. Same endpoints as any other class: current, forward, or webhooks. Not a paid add-on. Landing page: /agriculture/.

Point the client at https://tou.tools/mcp with the same tou_… API key you use for REST. Tools: get_current_period, get_schedule, get_forward_schedule, list_utilities, list_rate_plans. Every tool call counts as one API call — don't loop get_current_period in a chat session or you'll burn the Free 500-call cap. Docs: /docs/#mcp.