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) - INLINECODE1 (optional, default:
https://api.umami.is) - INLINECODE3 (optional default site)
- INLINECODE4 (optional:
cloud or self-hosted, default: cloud)
API path conventions (explicit)
- - Umami Cloud: INLINECODE8
- Self-hosted Umami: INLINECODE9
The script supports both:
- -
--deployment cloud → uses cloud behavior (/v1 + x-umami-api-key) - INLINECODE13 → uses self-hosted behavior (
/api + Authorization: Bearer ...)
Read-only workflow
- 1. Pick endpoint from docs or
references/read-endpoints.md. - Run
scripts/umami_query.py with endpoint + params. - Use presets (
today, last7d, etc.) or custom startAt/endAt. - Analyze returned JSON for the user task.
Quick commands
CODEBLOCK0
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 .... - INLINECODE28 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: INLINECODE36
- Query helper: INLINECODE37
技能名称: umami-stats
详细描述:
Umami Stats（只读API技能）
将此技能用作数据访问层：获取Umami分析数据，然后让智能体决定分析/策略。
所需环境变量
- - UMAMIAPIKEY（必需）
- UMAMIBASEURL（可选，默认值：https://api.umami.is）
- UMAMIWEBSITEID（可选默认站点）
- UMAMI_DEPLOYMENT（可选：cloud或self-hosted，默认值：cloud）
API路径约定（明确说明）
- - Umami Cloud： https://api.umami.is/v1/...
- 自托管Umami： https:///api/...
脚本支持两种模式：
- - --deployment cloud → 使用云模式行为（/v1 + x-umami-api-key）
- --deployment self-hosted → 使用自托管模式行为（/api + Authorization: Bearer ...）
只读工作流程
- 1. 从文档或references/read-endpoints.md中选择端点。
- 使用端点+参数运行scripts/umami_query.py。
- 使用预设（today、last7d等）或自定义startAt/endAt。
- 分析返回的JSON以完成用户任务。
快速命令
bash
1) 列出网站
python3 scripts/umami_query.py --endpoint /v1/websites
2) 最近7天的网站统计（默认网站来自环境变量）
python3 scripts/umami_query.py \
--endpoint /v1/websites/{websiteId}/stats \
--preset last7d
3) 使用显式网站ID的顶级页面
python3 scripts/umami_query.py \
--endpoint /v1/websites/{websiteId}/pageviews \
--website-id $UMAMI
WEBSITEID \
--preset last30d
4) 使用自定义时间窗口的事件序列
python3 scripts/umami_query.py \
--endpoint /v1/websites/{websiteId}/events/series \
--param startAt=1738368000000 \
--param endAt=1738972799000
5) 云模式下的旧路径自动映射（/api/... -> /v1/...）
python3 scripts/umami_query.py --endpoint /api/websites/{websiteId}/stats --preset last7d
6) 自托管示例（/v1/... 自动映射到 /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 / UMAMIWEBSITEID添加websiteId。
- 在Umami Cloud上，/v1/users/端点对于普通用户API密钥可能返回403（这在许多账户中是预期的）。
资源
- - 端点映射：references/read-endpoints.md
- 查询助手：scripts/umami_query.py
