---
title: Live Data — Reference
---

# Live Data — How the Dashboard Refreshes

All dashboard pages poll the State Hub API automatically. No manual refresh is ever needed.

---

## Poll interval

Most live pages fetch fresh data from `http://127.0.0.1:8000` every **15 seconds**
using an async generator loop. The overview page uses a heavier bounded read
model and refreshes every **60 seconds**. The previous data stays visible while
the next request is in flight, so the UI never goes blank.

---

## The live indicator

The **●** dot in the top-right corner of each page shows the current connection state:

| Indicator | Meaning |
|---|---|
| **● Live · updated HH:MM:SS** | Last poll succeeded — data is current as of that time |
| **● Stale · last successful update HH:MM:SS** | Last refresh failed, but cached page data is still visible |
| **● Offline — run: `make api`** | API is unreachable — the dot turns red |

The timestamp updates on every successful poll. If you see a time that is more than ~30 seconds in the past, the poll is stalled (browser tab backgrounded or network issue) — reloading the page resets the loop.

---

## Offline recovery

If the API goes offline while you are viewing a page:

1. The indicator turns red immediately on the next failed poll (within 15 s)
2. The last successfully loaded data stays visible
3. Once the API restarts, the indicator turns green on the next poll — **no page reload needed**

To restart the API:

```bash
cd ~/state-hub
make api      # db + migrate + uvicorn (restarts if already running)
```

---

## Which data each page polls

| Page | Endpoints |
|---|---|
| Overview | `/state/overview`, `/decisions/?decision_type=pending` |
| Workplans | `/workplans/`, `/topics/`, `/state/summary` |
| Decisions | `/decisions/?limit=500`, `/topics/` |
| Progress | `/progress/?limit=500` |

All endpoints are read-only GET requests. The dashboard never writes to the API.

`/state/summary` is revision-cached server-side. Repeated polls with unchanged
hub data return `X-StateHub-Cache: hit-revision` without rebuilding the full
snapshot. Prefer `/state/overview` on the Overview page (lighter bounded
read model).

---

*Poll interval: 15 s for most pages, 60 s for Overview. Data is refreshed in the background — the page never reloads itself.*
