Swetrix API 使用详解

目标：把 Swetrix 社区版（CE）v5.4.1 的三类 API——事件上报（Events API）、管理（Admin API）、统计查询（Statistics API v2）——按「认证获取 → 端点 → 参数 → 实测请求/响应」的完整链路讲透，读者照做即可完成从上报到取数的闭环。本文全部请求与响应均为在 Ubuntu 22.04 服务器上对自托管 v5.4.1 实例的 curl 实测回显（实例地址 http://192.168.1.200:8131，读者按自身实例替换），云端对照口径标注自官方文档（swetrix.com/docs，2026-10-30 查询）。

一、环境信息

• Swetrix CE：v5.4.1（官方最新稳定版），自托管部署（部署过程见 《Swetrix Docker Compose 部署指南》）
• 实例入口：http://192.168.1.200:8131（nginx 统一入口；前端 /、API 前缀 /backend/）
• API 基准路径：自托管为 http://192.168.1.200:8131/backend/；Swetrix 云服务为 https://api.swetrix.com/（云端无 /backend 前缀，其余端点一致）
• 测试工具：curl 7.81（Ubuntu 22.04 自带）
• 测试项目：demo（Project ID SojpySDiPDTp，实测创建）
• 官方文档基准：Events API / Admin API / Statistics API v2 三个参考页（2026-10-30 版）

二、前置条件（端点、认证与客户端工具）

三类 API、两种认证方式，先用一张表分清：

两种凭据的获取途径：

1. JWT 令牌对（accessToken + refreshToken）：注册/登录响应直接返回，accessToken 约 30 分钟有效（实测响应中的 exp - iat = 1800 秒），过期用 POST /v1/auth/refresh-token 换新；
2. 个人 API Key：登录后调 POST /user/api-key 生成（注意：该端点无 /v1 前缀），返回 UUID 形态字符串，长期有效、用于脚本与报表工具。

客户端工具用 curl 即可；浏览器场景直接用官方 tracker-js 脚本（apiURL 指向 [BASE_URL]/backend/v1/log），无需手写 HTTP。

💡 说明：JWT 与 API Key 的分工——浏览器仪表盘走 JWT 会话；服务端脚本、CI、报表系统走 API Key。X-Api-Key 无法用于注册/登录等账号操作，Authorization: Bearer 不能替代 X-Api-Key 访问 Statistics v2 的计划限流档位（两者在 Admin API 上等价）。

三、API 总览（协议、版本与限流约定）

• 协议与格式：全部为 HTTPS 上的 JSON REST；请求与响应 Content-Type: application/json（事件上报端点响应体为空 JSON，Content-Length: 2）。
• 版本形态：路径内嵌版本——/v1/（Auth 与 Admin）、/v2/（Statistics v2，v1 统计 API 仍可用，v2 为增量式重设计：每个端点只返回一类数据——summary、timeseries 或 breakdown）；事件上报 /log* 与用户设置 /user/* 无版本前缀。v1 与无前缀路径混用是自托管实测的高频踩坑点（见第十章 FAQ）。
• 限流约定（官方文档口径，按云服务计划分档，自托管实例不限计划但实现同源）：Admin/Statistics API Standard 计划 300 请求/小时、Plus 计划 6000 请求/小时、Enterprise 可定制；注册等敏感端点按 IP 限流（源码实测注册端点为每 IP 5 次）。
• 统一响应包（Statistics v2）：所有 v2 端点返回 {"data": <载荷>, "meta": {...}}，meta 回显解析后的查询参数（时间边界、时区、过滤器、分页），见 6.1 实测。

四、认证与首次调用（curl 实测）

4.1 注册并取得 JWT 令牌

curl -s -X POST http://192.168.1.200:8131/backend/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2E3r4","checkIfLeaked":false}'

实测回显（输出节选）：

{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkODdjN2VjMS01NTNiLTRlNWQtYTQ1NC00ZjUxMDU1MzdmY2QiLCJpc1NlY29uZEZhY3RvckF1dGhlbnRpY2F0ZWQiOnRydWUsImlhdCI6MTc5MzMzMTU2OCwiZXhwIjoxNzkzMzMzMzY4fQ.IaT6Pvx9J8jqVyOg97qqt_5VcD1i4cp6OkdOc9TPtAw","refreshToken":"eyJhbGciOiJIUzI1NiIs…","user":{"id":"d87c7ec1-553b-4e5d-a454-4f5105537fcd","email":"admin@example.com",…}}

要点：checkIfLeaked 必传（布尔），密码长度 8–72 位；已有账号换用 POST /v1/auth/login，请求体与响应结构相同。

4.2 生成个人 API Key

curl -s -X POST http://192.168.1.200:8131/backend/user/api-key \
  -H "Authorization: Bearer <accessToken>"

实测回显：

{
    "apiKey": "eaa96f63-f432-4a73-841e-3d11e2e70ce8"
}

⚠️ 注意：上述 key 是本文演示实例的一次性实测产物，实验后已销毁；读者须用自己账号生成。端点路径是 /user/api-key 而非 /v1/user/api-key——多打 /v1 会得到 404 {"message":"Cannot POST /v1/user/api-key"}（实测确认）。

4.3 首次鉴权调用验证

用刚生成的 key 调 Admin API 列出项目：

curl -s http://192.168.1.200:8131/backend/v1/project \
  -H "X-Api-Key: eaa96f63-f432-4a73-841e-3d11e2e70ce8"

实测回显（输出节选）：

{
    "results": [
        {
            "id": "SojpySDiPDTp",
            "name": "demo",
            "origins": [],
            "ipBlacklist": [],
            "ipWhitelist": [],
            "countryBlacklist": [],
            "active": true,
            "public": false,
            "isPasswordProtected": false,
            "botsProtectionLevel": "basic",
            "adminId": "d87c7ec1-553b-4e5d-a454-4f5105537fcd",
            "websiteUrl": null,
            …
        }
    ]
}

不带凭据调用的对照（实测）：

{"message":"Unauthorized","statusCode":401}

五、各 API 域详解

5.1 Events API（事件上报）

自托管时把云端 https://api.swetrix.com 换成 [BASE_URL]/backend，端点与载荷完全一致。所有 /log* 端点依赖 User-Agent 与访客 IP（X-Forwarded-For 或发送方 IP）构造临时访客会话——缺失时 API 仍成功，但独立访客/实时访客/地理数据失真；项目开启 Strict 反机器人时，机房 IP 事件会被静默丢弃（响应依旧成功，需到 Shields 报告核对）。

5.1.1 POST /log —— 页面浏览事件

请求：

curl -i -X POST http://192.168.1.200:8131/backend/log \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126 Safari/537.36' \
  -H 'X-Forwarded-For: 89.160.20.112' \
  -d '{"pid":"SojpySDiPDTp","pg":"/home","tz":"Europe/Berlin","lc":"en-US","ref":"https://www.google.com/"}'

实测回显（响应头节选，响应体为空 JSON）：

HTTP/1.1 201 Created
Server: nginx/1.31.1
Content-Type: application/json; charset=utf-8
Content-Length: 2

载荷字段（官方 Events API 参考）：pid（必填）、pg 页面路径、tz 访客时区（IP 定位失败时的地理兜底）、lc locale、ref 来源 URL、so/me/ca 流量来源/媒介/活动（UTM）、unique 仅计独立访问、perf 性能指标对象（dns/tls/conn/response/render/dom_load/page_load/ttfb，毫秒）。

5.1.2 POST /log/custom —— 自定义事件

请求：

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://192.168.1.200:8131/backend/log/custom \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) Chrome/126' \
  -H 'X-Forwarded-For: 89.160.20.112' \
  -d '{"pid":"SojpySDiPDTp","ev":"signup","pg":"/home","meta":{"plan":"pro"}}'

实测回显：

201

载荷要点：ev 事件名必填（≤256 字符，可用任意字符）；meta 是自定义属性对象——值必须是原始类型（字符串/数字/布尔/null），最多 100 个键，键值总长 ≤2000 字符；unique: true 时每会话只记一次。

5.1.3 POST /log/error —— 客户端错误事件

请求：

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://192.168.1.200:8131/backend/log/error \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) Chrome/126' \
  -H 'X-Forwarded-For: 89.160.20.112' \
  -d '{"pid":"SojpySDiPDTp","name":"TypeError","message":"x is not a function","lineno":42}'

实测回显：

201

载荷要点：name 必填（≤200 字符）；message ≤2000；stackTrace ≤7500；错误在仪表盘 Errors 标签页聚合。

5.1.4 其余事件端点速查

5.2 Admin API（项目管理）

认证：X-Api-Key 或 Authorization: Bearer 均可（4.3 已实测）。项目域端点全表（官方 Admin API 参考，2026-10-30）：

PUT 更新时的三个高价值字段（官方文档口径）：origins 域名白名单（支持通配，空数组=放行全部，生产务必配置）；ipBlacklist 屏蔽自家访问的 IP/CIDR；botsProtectionLevel 取 off/basic/strict（默认 basic，实测项目列表回显一致）。

组织域（POST /v1/organisation 创建、成员邀请 role 取 owner/admin/viewer）与项目置顶等端点结构同上，从略。

5.3 Statistics API v2（统计取数）

全部端点按项目 scope：/v2/projects/{pid}/...；公开项目可免 key（public: true）。端点分组：

5.3.1 GET /v2/projects/:pid/traffic/summary —— 概览

请求：

curl -s "http://192.168.1.200:8131/backend/v2/projects/SojpySDiPDTp/traffic/summary?period=1d" \
  -H "X-Api-Key: eaa96f63-f432-4a73-841e-3d11e2e70ce8"

实测回显（上报 1 个 pageview 后）：

{
    "data": {
        "current": {
            "visitors": 1,
            "pageviews": 1,
            "users": 1,
            "bounce_rate": 100,
            "session_duration": 0
        },
        "previous": {
            "visitors": 0,
            "pageviews": 0,
            "users": 0,
            "bounce_rate": 0,
            "session_duration": 0
        },
        "change": {
            "visitors": 1,
            "pageviews": 1,
            "users": 1,
            "bounce_rate": -100,
            "session_duration": 0
        }
    },
    "meta": {
        "pid": "SojpySDiPDTp",
        "period": "1d",
        "timezone": "Etc/GMT",
        "appliedFilters": []
    }
}

解读：current/previous/change 三段对比结构是 summary 的固定形态；单样本会话的 bounce_rate=100、session_duration=0 符合预期。

5.3.2 GET /v2/projects/:pid/traffic/breakdown —— 维度分解

请求（按页面分解）：

curl -s "http://192.168.1.200:8131/backend/v2/projects/SojpySDiPDTp/traffic/breakdown?dimension=page&period=1d" \
  -H "X-Api-Key: eaa96f63-f432-4a73-841e-3d11e2e70ce8"

实测回显：

{
    "data": [
        {
            "value": "/home",
            "visitors": 1,
            "pageviews": 1
        }
    ],
    "meta": {
        "pid": "SojpySDiPDTp",
        "period": "1d",
        "from": "2026-10-29T03:00:00Z",
        "to": "2026-10-30T03:41:09Z",
        "timezone": "Etc/GMT",
        "appliedFilters": [],
        "dimension": "page",
        "metrics": ["visitors", "pageviews"],
        "limit": 30,
        "offset": 0,
        "sort": "visitors:desc",
        "total": 1
    }
}

按国家分解（同参数 dimension=country）实测回显：

{
    "data": [
        {
            "value": "SE",
            "visitors": 1,
            "pageviews": 1
        }
    ],
    "meta": { "…同上，dimension": "country", "total": 1 }
}

💡 说明：value: "SE" 正是内置 GeoIP 库把测试 IP 89.160.20.112（瑞典地址段）识别出的国家码——验证了自托管默认地理库开箱可用。

维度参数传错名的对照实测（dimension=pages）：

{
    "message": "Unknown traffic dimension 'pages'. Supported dimensions: country, region, city, page, host, locale, browser, browser_version, os, os_version, device, referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content, isp, organization, user_type, connection_type, entry_page, exit_page",
    "error": "Unprocessable Entity",
    "statusCode": 422
}

该 422 回显顺带给出了流量域全部 23 个合法维度，可当速查表用（isp/organization/user_type/connection_type 四个网络维度需配合付费 GeoIP 库，见配置篇 5.5 节）。

5.3.3 GET /v2/projects/:pid/traffic/custom-events —— 自定义事件统计

请求：

curl -s "http://192.168.1.200:8131/backend/v2/projects/SojpySDiPDTp/traffic/custom-events?period=1d" \
  -H "X-Api-Key: eaa96f63-f432-4a73-841e-3d11e2e70ce8"

实测回显：

{
    "data": [
        {
            "event": "signup",
            "count": 1
        }
    ],
    "meta": {
        "pid": "SojpySDiPDTp",
        "period": "1d",
        "from": "2026-10-29T03:00:00Z",
        "to": "2026-10-30T03:41:09Z",
        "timezone": "Etc/GMT",
        "appliedFilters": [],
        "total": 1,
        "limit": 30,
        "offset": 0
    }
}

5.4 错误码约定（实测汇总）

六、分页、过滤与排序通用约定

Statistics v2 的分解/列表类端点共享一套查询约定（meta 中回显实测值，无需猜行为）：

• 分页：limit（默认 30）+ offset，meta.total 给总数；
• 排序：sort=指标名:方向（实测默认 visitors:desc）；
• 时间范围：period 枚举 1h/today/yesterday/1d/7d(默认)/4w/3M/12M/24M/all，或成对的 from+to（ISO 8601，与 period 互斥）；timezone 默认 Etc/GMT；
• 时间桶：timeBucket 取 minute/hour/day/month/year，v2 端点可省略（按范围自动选最细桶）；period=all 时看 meta.allowedTimeBuckets；
• 过滤：meta.appliedFilters 回显生效过滤器；指标名经 metrics 逗号列表按数据类型校验，全量清单走 GET /v2/projects/:pid/dimensions 发现端点。

七、常见问题

Q1：事件上报 201 但仪表盘没数据？ 先核对 pid 是否拼写正确（12 位串，实测创建项目返回的 id）；再确认浏览器/请求是否带上了 User-Agent 与真实 X-Forwarded-For——项目开了 botsProtectionLevel: strict 时机房 IP 事件被静默丢弃，到 Project settings → Shields → Blocked traffic 核对丢弃记录。

Q2：Cannot POST /v1/user/api-key 之类的 404？ Swetrix 路径版本混用：Auth/Admin 走 /v1/...，用户设置与事件上报无前缀，Statistics v2 走 /v2/...。按本文第二章的表对号入座。

Q3：JWT 很快过期，脚本怎么长期跑？ accessToken 约 30 分钟有效（实测 exp-iat=1800），脚本启动时先调 POST /v1/auth/login 换新 token，或改用长期有效的个人 API Key（X-Api-Key），后者是自动化场景的推荐姿势。

Q4：/log/revenue 返回 401？ 它是 /log 家族里唯一要求 X-Api-Key 的端点（防浏览器伪造交易），确认请求头带了个人 API Key 且不在浏览器端调用。

Q5：自托管和云服务的 API 有差异吗？ 端点与载荷一致，差异在地址（[BASE_URL]/backend 对 https://api.swetrix.com）与限流（自托管不受云计划档位约束）；云服务专属功能（会话回放、收入分析等）对应的查询端点在社区版无数据源。

八、参考链接

• 官方 Events API 参考：https://swetrix.com/docs/events-api
• 官方 Statistics API v2 参考：https://swetrix.com/docs/statistics-api-v2
• 官方 Statistics API v1 参考：https://swetrix.com/docs/statistics-api
• 官方 Admin API 参考：https://swetrix.com/docs/admin-api
• 跟踪脚本参考（apiURL 自托管口径）：https://swetrix.com/docs/swetrix-js-reference
• 本站部署篇：《Swetrix Docker Compose 部署指南》
• 本站配置篇：《Swetrix v5.4.1 配置参数详解》
• 本站认知篇：《Swetrix 介绍与选型指南》

实测环境与查询日期：自托管 Swetrix CE v5.4.1，2026-10-30；全部回显为当日 curl 实测，演示用 API Key 已在实验后吊销。