umami-stats

# Umami Stats (Read-only API skill)

Use this skill as a **data-access layer**: fetch Umami analytics data, then let the agent decide analysis/strategy.

## Required environment variables

- `UMAMI_API_KEY` (required)
- `UMAMI_BASE_URL` (optional, default: `https://api.umami.is`)
- `UMAMI_WEBSITE_ID` (optional default site)
- `UMAMI_DEPLOYMENT` (optional: `cloud` or `self-hosted`, default: `cloud`)

## API path conventions (explicit)

- **Umami Cloud:** `https://api.umami.is/v1/...`
- **Self-hosted Umami:** `https://<your-host>/api/...`

The script supports both:
- `--deployment cloud` → uses cloud behavior (`/v1` + `x-umami-api-key`)
- `--deployment self-hosted` → uses self-hosted behavior (`/api` + `Authorization: Bearer ...`)

## Read-only workflow

1. Pick endpoint from docs or `references/read-endpoints.md`.
2. Run `scripts/umami_query.py` with endpoint + params.
3. Use presets (`today`, `last7d`, etc.) or custom `startAt`/`endAt`.
4. Analyze returned JSON for the user task.

## Quick commands

```bash
# 1) List websites
python3 scripts/umami_query.py --endpoint /v1/websites

# 2) Website stats for last 7 days (default website from env)
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/stats \
  --preset last7d

# 3) Top pages with explicit website id
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/pageviews \
  --website-id "$UMAMI_WEBSITE_ID" \
  --preset last30d

# 4) Events series with custom window
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/events/series \
  --param startAt=1738368000000 \
  --param endAt=1738972799000

# 5) Legacy path auto-mapping in cloud mode (/api/... -> /v1/...)
python3 scripts/umami_query.py --endpoint /api/websites/{websiteId}/stats --preset last7d

# 6) Self-hosted example (/v1/... auto-maps to /api/...)
python3 scripts/umami_query.py \
  --deployment self-hosted \
  --base-url "https://umami.example.com" \
  --endpoint /v1/websites/{websiteId}/stats \
  --preset last7d
```

## Natural trigger examples

- “How was traffic this week?”
- “Top pages in the last 30 days”
- “Show event trends for signup clicks”
- “Compare current week vs previous week”
- “Give me raw Umami data to build a marketing experiment plan”

## Notes

- Keep requests **read-only** (`GET`).
- Prefer explicit time windows for reproducibility.
- For unknown endpoints, consult `https://v2.umami.is/docs/api` and then query with the script.
- Prefer `/v1/...` endpoints in cloud mode, `/api/...` in self-hosted mode.
- Auth headers are mode-specific: cloud uses `x-umami-api-key`; self-hosted uses `Authorization: Bearer ...`.
- `metrics` endpoints require a `type` query param. The script now auto-defaults to `type=url` if omitted.
- For `/v1/reports/*` endpoints, the script auto-adds `websiteId` from `--website-id` / `UMAMI_WEBSITE_ID` when available.
- On Umami Cloud, `/v1/users/*` endpoints can return 403 for normal user API keys (expected in many accounts).

## Resources

- Endpoint map: `references/read-endpoints.md`
- Query helper: `scripts/umami_query.py`