Plost API · v1

统计数据 API

从你的网站、服务端或自动化工具读取站点统计。

返回站点 OpenAPI 3.1

1. 获取调用凭证

进入站点设置 → 可见性 → 分享链接，为调用方创建单独命名的分享链接。
取 /share/ 后面的最后一段作为 Bearer 凭证。每个凭证只对应一个站点。
删除对应分享链接即可撤销 API 调用；无需改账号密码。

这是分享凭证，不是独立 API Key；持有者也能访问对应分享报表。请仅保存在服务端环境变量中，勿写入网页 JS、公开仓库或 URL。

2. 请求接口

GET /api/v1/stats

Authorization: Bearer YOUR_SHARE_CREDENTIAL

参数	说明
period	`summary` 默认，一次返回在线、今天和昨天；也可选择 live、today、yesterday。
domain	可选，填写已存储的站点域名；必须与凭证对应站点一致。省略时直接读取凭证对应站点。

cURL

# 先在服务端设置环境变量 PLOST_TOKEN
curl --fail-with-body '/api/v1/stats?period=summary' \
  -H "Authorization: Bearer $PLOST_TOKEN"

JavaScript / Node.js

const response = await fetch('/api/v1/stats?period=summary', {
  headers: { Authorization: `Bearer ${process.env.PLOST_TOKEN}` }
});
if (!response.ok) throw new Error(`Plost HTTP ${response.status}`);
const stats = await response.json();
console.log(stats.data);

Python

import os, requests
response = requests.get(
    '/api/v1/stats?period=summary',
    headers={'Authorization': 'Bearer ' + os.environ['PLOST_TOKEN']},
    timeout=15,
)
response.raise_for_status()
print(response.json()['data'])

范围报表与站点检查

GET /api/v1/report?range=today&details=1

使用同一个站点分享凭证。range 支持 today、yesterday、24h、7d、30d、month；details=0 仅取汇总，details=1 同时读取趋势、前五热门页面和来源。今天和多日范围按站点时区划分；24h 为滚动 24 小时。

返回 data.totals、data.previous 与 data.online，趋势位于 details.series，排行按访客数统计。今日对比昨日全天，本月对比上月全天；当前期间尚未结束。多日总访客为整个范围去重人数，不是逐日相加。未来时段的趋势值为 null。

health 返回网站可用性、证书及域名到期日期，复用服务端已保存的检查结果，不会触发探测；超过 10 分钟的 HTTP 结果显示为未知，到期查询失败时保留日期并标记 stale。接口不暴露检查路径、IP、注册商或原始诊断；检查信息暂不可用不会影响流量统计。完整字段见 OpenAPI。

3. 响应与统计口径

以下为 summary 示例数据，不是实际站点统计。live 仅返回 online；today / yesterday 返回 date、visitors、visits、pageviews。

{
  "apiVersion": "1",
  "site": {
    "domain": "example.com",
    "timezone": "Asia/Shanghai"
  },
  "period": "summary",
  "generatedAt": "2026-10-23T08:00:00.000Z",
  "onlineWindowSeconds": 300,
  "data": {
    "online": 6,
    "today": {
      "date": "2026-10-23",
      "visitors": 120,
      "visits": 145,
      "pageviews": 320
    },
    "yesterday": {
      "date": "2026-10-22",
      "visitors": 100,
      "visits": 118,
      "pageviews": 260
    }
  }
}

字段	含义
`online`	最近 5 分钟有事件上报的去重访客数，不代表持续在线连接。
`visitors`	独立访客数（UV），按匿名访客 ID 去重。
`visits`	访问/会话次数，按访问 ID 去重；跨小时或闲置 30 分钟后开始新访问。
`pageviews`	页面浏览量（PV），仅计 pageview 事件。
`site.timezone`	今天/昨天按站点配置时区划分自然日，兼容夏令时；不是最近 24 小时。
`generatedAt`	接口生成响应的 UTC 时间，不是最后一条访问的时间。

4. 错误处理

{"error":{"code":"unauthorized","message":"…"}}

400	`invalid_parameter / invalid_period / invalid_domain`	检查参数；不支持重复参数或 URL 传凭证。
401	`unauthorized`	凭证缺失、格式错误、无效或已撤销。
403	`forbidden`	域名与凭证所属站点不匹配。
429	`rate_limited`	按 Retry-After 响应头等待后重试。
503	`service_unavailable`	数据服务不可用；请重试，不能当作访问量为零。

5. 调用约定

推荐每 30–60 秒查询一次。每个应用进程对单凭证限制 60 次/分钟；多进程部署需在反向代理另配统一限流。
今天的统计持续变化；埋点批量写入可能有短暂延迟。新采集使用持久匿名访客 ID，历史迁移和旧采集可能使用不同标识；不要将多天 UV 相加当作跨日去重人数。
接口只返回聚合数值，不返回账号、IP、访客明细或写操作。不支持带凭证的浏览器跨域请求；网页请通过自己的后端代理并缓存。
API v1 的现有字段保持兼容，客户端应忽略未来新增字段。AI 编程助手可读取 OpenAPI 规范生成调用代码，无需将真实凭证发送给 AI。

读取机器可用的 OpenAPI 规范