OpenAPI

业务系统要把指标嵌进自己的后台、外部 Agent 要把 evstats 当数据源时，用只读的 /api/v1。数字和后台 Stats 完全相同，因为调用的是同一个查询。

完整的路径、参数和返回字段见 API 参考，服务自己也在 GET /openapi.json 提供同一份契约（OpenAPI 3.0.3）。

创建接口密钥

右上角头像 → 个人设置 → 接口密钥。
点「创建」，起一个名字，比如「运营后台」。
对话框里复制密钥 evs_xxx。它只显示这一次，关掉之后只剩前缀。

每人最多 10 把。不用了可以停用或删除，停用后立即 40101。演示用户不能创建接口密钥。

接口密钥能读数据

不要把它写进前端代码、提交到仓库、贴进截图或聊天记录。用环境变量或密钥管理服务保存。写入密钥（evs_wk_）调用 /api/v1 一律 40101。

权限跟人走

密钥不绑定项目。它能看的项目，和创建它的人在后台能看的一样：管理员看全部，其他人看角色勾选的项目。
收回这个人的项目授权、改角色、停用这个人，他的所有密钥下一次请求就按新权限生效。
GET /api/v1/projects 只列出能看的项目；访问看不到的项目返回 40301。

调用

OpenAPI 取数：用接口密钥调 /api/v1，返回和仪表盘同一个查询的结果

bash

# 能看的项目
curl -sS -H "Authorization: Bearer evs_xxx" \
  "https://stats.example.com/api/v1/projects"

# 某个项目近一周的概览，并和上一周对比
curl -sS -H "Authorization: Bearer evs_xxx" \
  "https://stats.example.com/api/v1/projects/{projectId}/overview?from=2026-09-01&to=2026-09-07&compare=prev"

返回统一是这样的信封，data 的字段名和后台 Stats 相同：

json

{ "code": 0, "message": "ok", "data": { "pv": 1200, "uv": 300, "partial": [], "compare": { "pv": 1100, "uv": 290 } } }

code 不为 0 时看错误码。每个响应都带 X-Request-Id，统计响应还带 X-Evstats-Cache: hit|miss 和计算时间 X-Evstats-Computed-At。

嵌进自己的后台

在你自己的服务端取数，再交给页面，密钥不出服务端：

// Node 18+，放在你自己后台的服务端
const BASE = "https://stats.example.com/api/v1"
const KEY = process.env.EVSTATS_API_KEY // evs_xxx

export async function weeklyKpi(projectId, from, to) {
  const url = `${BASE}/projects/${projectId}/overview?from=${from}&to=${to}&compare=prev`
  const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } })
  const body = await res.json()
  if (body.code !== 0) throw new Error(`${body.code} ${body.message}`)
  const { pv, uv, bounce_rate, compare } = body.data
  return { pv, uv, bounce_rate, pvPrev: compare?.pv ?? null }
}

浏览器直接调用 /api/v1 也可以，跨域规则在「系统配置 → OpenAPI」的 openapi.cors，默认允许所有来源。但那样密钥就会出现在浏览器里，只适合放在可信的内部页面，并且用一个只授权了必要项目的账号来建密钥。

参数

与后台完全相同：

参数	说明
`from`、`to`	`YYYY-MM-DD`，按项目时区，含首尾两天。除画像等少数接口外必填
`compare`	`prev`：和上一段对比
`pf`	筛选，可以重复：`key,op,value`，`op` 是 `eq`、`neq`、`contains`、`exists`
各模块的参数	例如漏斗的 `steps`、`window_hours`，趋势的 `grain`、`metric`

超过模块的最长跨度返回 40001，提示里写明上限，见限制与上限。没有数据时返回空数组，不是 40401。

有什么、没有什么

有	没有
项目列表、概览、汇总、趋势、访客、页面、搜索词	CSV 导出（`format=csv` 会被拒绝）
用户画像（按 `distinct_id`）、活跃、忠诚度、流失、留存、回流沉默	实时访问
事件、事件日志（`limit` 默认 20，最大 100）、自定义分析、漏斗、路径	自定义 SQL
热力图格子、会话回放列表、归因、实验结果	回放正文、看板、书签
事件名、属性键	任何写操作、登录、系统管理

限流

每把密钥全集群 60 次 / 分钟，多台进程共用这个计数；超出返回 42901。需要更多时，给结果加缓存，或者不同系统各建一把密钥。结果本身在服务端也有短缓存（默认 60 秒），和后台共用。

给外部 Agent

把 evstats 交给 ChatGPT 或别的 Agent 当数据源，见给外部 Agent 用。

OpenAPI ​

创建接口密钥 ​

权限跟人走 ​

调用 ​

嵌进自己的后台 ​

参数 ​

有什么、没有什么 ​

限流 ​

给外部 Agent ​