umami-stats

使用环境提供的 API 密钥通过 API 查询 Umami Cloud (v2) 分析数据。当代理需要网站流量、页面、事件、会话、实时、报告或归因数据进行分析、规划、实验或监控时使用。包括只读 API 查询模式、端点选择指南以及用于灵活端点 + 时间范围请求的可重用脚本。

# 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`

---

## 中文说明

# Umami Stats（只读 API 技能）

将此技能用作**数据访问层**：获取 Umami 分析数据，然后让代理决定分析/策略。

## 所需环境变量

- `UMAMI_API_KEY`（必需）
- `UMAMI_BASE_URL`（可选，默认值：`https://api.umami.is`）
- `UMAMI_WEBSITE_ID`（可选的默认站点）
- `UMAMI_DEPLOYMENT`（可选：`cloud` 或 `self-hosted`，默认值：`cloud`）

## API 路径约定（明确）

- **Umami Cloud：** `https://api.umami.is/v1/...`
- **自托管 Umami：** `https://<your-host>/api/...`

该脚本同时支持两者：
- `--deployment cloud` → 使用云端行为（`/v1` + `x-umami-api-key`）
- `--deployment self-hosted` → 使用自托管行为（`/api` + `Authorization: Bearer ...`）

## 只读工作流

1. 从文档或 `references/read-endpoints.md` 中选择端点。
2. 使用端点 + 参数运行 `scripts/umami_query.py`。
3. 使用预设（`today`、`last7d` 等）或自定义 `startAt`/`endAt`。
4. 针对用户任务分析返回的 JSON。

## 快捷命令

```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
```

## 自然触发示例

- “本周流量如何？”
- “最近 30 天的热门页面”
- “显示注册点击的事件趋势”
- “对比本周与上周”
- “给我原始的 Umami 数据以构建营销实验计划”

## 注意事项

- 保持请求为**只读**（`GET`）。
- 优先使用明确的时间窗口以保证可复现性。
- 对于未知端点，请查阅 `https://v2.umami.is/docs/api`，然后使用该脚本进行查询。
- 在云端模式下优先使用 `/v1/...` 端点，在自托管模式下优先使用 `/api/...`。
- 认证头取决于模式：云端使用 `x-umami-api-key`；自托管使用 `Authorization: Bearer ...`。
- `metrics` 端点需要 `type` 查询参数。如果省略，脚本现在会自动默认为 `type=url`。
- 对于 `/v1/reports/*` 端点，脚本会在可用时自动从 `--website-id` / `UMAMI_WEBSITE_ID` 添加 `websiteId`。
- 在 Umami Cloud 上，普通用户 API 密钥访问 `/v1/users/*` 端点可能返回 403（在许多账户中属于预期情况）。

## 资源

- 端点映射：`references/read-endpoints.md`
- 查询助手：`scripts/umami_query.py`