> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotwatt.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Data sources

> FoxESS, Octopus, and Open-Meteo — what PilotWatt fetches and how often.

| Source                 | Data                                                                      | Refresh             | Cache TTL                                               |
| ---------------------- | ------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------- |
| **FoxESS Cloud API**   | Battery SoC, solar kW, grid import/export, work mode                      | \~5 min (API limit) | State 5 min; schedule get 60 s                          |
| **Octopus Energy API** | Agile export rates (48h), settled export consumption, IO window (GraphQL) | Rates \~30 min      | 30 min (rates + IO window); longer for historical slots |
| **Open-Meteo**         | Hourly shortwave radiation → estimated kWh                                | \~1 hour            | 1 hour per user                                         |

## FoxESS

* Auth: API key + signed requests
* Used for: live dashboard, manual override, EV import inference, scheduler push

## Octopus

* Auth: personal API key (Basic)
* Used for: rates chart, earnings, optimiser scoring
* Requires export MPAN + meter serial
* Export earnings data typically lags 24–48 hours behind real time. PilotWatt shows the most recent settled data available.

## Open-Meteo

* No API key
* Location from your Settings / onboarding postcode
* kWh estimate: `(radiation × panel area × efficiency) / 1000` using env defaults unless customised

## Degraded mode

If an upstream API fails, PilotWatt shows the last cached value with a stale timestamp and retry where possible. The recommendation may switch to "insufficient data" if inputs are too old.