Analytics REST API
The Privatus Analytics REST API: add .json to any app URL and send a token. Conventions and a reference of every operation, generated from the code.
Every page and action in Privatus Analytics is also an API endpoint. There's no
separate /api/v1: add .json to a URL and send an API token.
sh
curl https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=7d \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
json
{
"data": {
"period": { "from": "2026-09-23T00:00:00Z", "to": "2026-09-30T00:00:00Z" },
"metrics": {
"visitors": 1840, "visits": 2310, "pageviews": 5122,
"views_per_visit": 2.22, "bounce_rate": 41.3,
"visit_duration": 48000, "revenue": 129900
}
}
}
The reference below lists every operation with its method, path, permission, input schema and response schema. It's generated from the running code, as is the OpenAPI 3.1 document, so neither can drift from what the server does. The same operations are MCP tools.
Conventions#
| Base URL | https://privatusanalytics.com |
| Format | JSON. Add .json to the path (or send Accept: application/json) |
| Auth | Authorization: Bearer pat_… (Authentication) |
| Ids | Public ids with a prefix: ws_… workspaces, pa_… sites, seg_… segments, wh_… webhooks |
| Reads | GET with query parameters |
| Writes | POST, PATCH, DELETE with a JSON body of flat fields |
| Success | { "data": … }, plus "meta" for lists |
| Errors | { "error": { "code", "message", "details" } } (Errors) |
| Lists | page and per_page (max 100) (Pagination) |
| Times | ISO 8601 in UTC. Date parameters (from, to) are days in the site's timezone |
| Money | Minor units (cents) in the site currency, e.g. revenue: 129900 = 1,299.00 |
| Durations | Milliseconds |
Common tasks#
| Task | Operation |
|---|---|
| List workspaces | GET /workspaces.json |
| List sites | GET /workspaces/{workspace_id}/sites.json |
| Headline metrics | GET /sites/{site_id}/stats/aggregate.json |
| Chart data | GET /sites/{site_id}/stats/timeseries.json |
| Top pages, sources, countries… | GET /sites/{site_id}/breakdown/{dimension}.json |
| Everything on the Overview | GET /sites/{site_id}/overview.json |
| Live visitors | GET /sites/{site_id}/live.json |
| Add a note (e.g. a deploy) | POST /sites/{site_id}/notes.json |
See Stats endpoints and Examples.
In this section#
Authentication · Errors · Pagination · Rate limits · Filters · Stats endpoints · Examples · Webhooks · Changelog and deprecation
Sending data in is a different API: see Server-side ingest.
所有操作
身份验证
发送 Authorization: Bearer pat_…。请在工作区设置的 API 令牌下创建令牌。身份验证指南。
处处支持 JSON
在任意路径后添加 .json。响应为 { "data": … }，错误为 { "error": { "code", "message" } }。错误。
MCP
使用相同的令牌向 https://privatusanalytics.com/mcp POST JSON-RPC。下面的每个操作都是一个工具。MCP 指南。
下载 openapi.json · 285 个操作
API 令牌
POST
/workspaces/:workspace_id/api_tokens.json
创建 API 令牌（令牌只返回一次）
api_tokens_create
权限： member
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "用于识别令牌的名称",
"examples": [
"CI deploys"
]
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "权限（省略则为您的全部权限，空列表会被拒绝）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制为这些站点 ID（pa_…）。留空 = 全部",
"default": []
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "过期时间（ISO 8601）。留空 = 永不过期"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
},
"description": "仅接受来自这些 IP/CIDR 的请求",
"default": []
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "令牌本身：仅在创建时返回"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "开头的字符，用于识别令牌"
},
"owner": {
"type": "string",
"description": "拥有它的成员的邮箱"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制为这些站点（空 = 全部）"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "获得它的 MCP 客户端"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active、expired 或 revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/api_tokens/:id.json
撤销 API 令牌
api_tokens_delete
权限： member
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/api_tokens/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "令牌本身：仅在创建时返回"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "开头的字符，用于识别令牌"
},
"owner": {
"type": "string",
"description": "拥有它的成员的邮箱"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制为这些站点（空 = 全部）"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "获得它的 MCP 客户端"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active、expired 或 revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/api_tokens.json
列出 API 令牌
api_tokens_list
权限： member
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"include_revoked": {
"type": "boolean",
"description": "同时列出已撤销和已过期的令牌",
"default": false
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "令牌本身：仅在创建时返回"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "开头的字符，用于识别令牌"
},
"owner": {
"type": "string",
"description": "拥有它的成员的邮箱"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制为这些站点（空 = 全部）"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "获得它的 MCP 客户端"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active、expired 或 revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
SCIM
POST
/scim/v2/Users.json
配置用户
scim_users_create
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/scim/v2/Users.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"userName": {
"type": "string",
"description": "邮箱地址"
},
"name": {
"type": "object",
"additionalProperties": true,
"description": "givenName、familyName、formatted",
"default": {}
},
"active": {
"type": "boolean",
"description": "工作区成员",
"default": true
}
},
"required": [
"userName"
]
}
响应数据
{
"type": "object"
}
DELETE
/scim/v2/Users/:id.json
取消配置用户
scim_users_delete
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X DELETE https://privatusanalytics.com/scim/v2/Users/:id.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object"
}
GET
/scim/v2/Users.json
列出已配置的用户
scim_users_list
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/scim/v2/Users.json输入
{
"type": "object",
"properties": {
"scim_filter": {
"type": "string",
"description": "SCIM 筛选条件（查询参数 `filter`），例如 userName eq \"[email protected]\""
},
"startIndex": {
"type": "integer",
"description": "第一个结果的索引（从 1 开始）",
"default": 1
},
"count": {
"type": "integer",
"description": "每页大小（最多 200）",
"default": 100
}
},
"required": []
}
响应数据
{
"type": "object"
}
GET
/scim/v2/Users/:id.json
获取已配置的用户
scim_users_get
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/scim/v2/Users/:id.json输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object"
}
PATCH
/scim/v2/Users/:id.json
更新用户（PATCH active、name）
scim_users_update
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X PATCH https://privatusanalytics.com/scim/v2/Users/:id.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"Operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "SCIM PatchOp 操作"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"Operations",
"id"
]
}
响应数据
{
"type": "object"
}
SSO
POST
/workspaces/:workspace_id/sso/activate.json
启用已测试的 SSO 配置
sso_activate
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/activate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登录方式（所有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已验证的邮箱域名"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
POST
/workspaces/:workspace_id/sso/deactivate.json
关闭 SSO（回到草稿）
sso_deactivate
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/deactivate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登录方式（所有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已验证的邮箱域名"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
POST
/workspaces/:workspace_id/sso/scim_token.json
生成新的 SCIM 令牌（只显示一次）
sso_scim_token
权限： workspace.manage
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/scim_token.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object"
}
GET
/workspaces/:workspace_id/sso.json
获取 SSO 设置
sso_get
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登录方式（所有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已验证的邮箱域名"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
PATCH
/workspaces/:workspace_id/sso.json
创建或更新 SSO 设置
sso_update
权限： workspace.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc",
"enum": [
"saml",
"oidc"
]
},
"idp_sso_url": {
"type": "string",
"description": "SAML：IdP 单点登录 URL"
},
"idp_entity_id": {
"type": "string",
"description": "SAML：IdP 实体 ID（issuer）"
},
"idp_cert": {
"type": "string",
"description": "SAML：IdP X.509 签名证书（PEM）"
},
"oidc_issuer": {
"type": "string",
"description": "OIDC：issuer URL（discovery）"
},
"oidc_client_id": {
"type": "string",
"description": "OIDC：客户端 ID"
},
"oidc_client_secret": {
"type": "string",
"description": "OIDC：客户端密钥（只写）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "使用此 SSO 的已验证邮箱域名"
},
"default_role": {
"type": "string",
"description": "通过 JIT 或 SCIM 创建的成员的角色",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing"
]
},
"jit_provisioning": {
"type": "boolean",
"description": "在首次 SSO 登录时创建成员"
},
"enforced": {
"type": "boolean",
"description": "仅允许 SSO 登录（需要已启用的配置）"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登录方式（所有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已验证的邮箱域名"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
Webhook
GET
/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json
列出 webhook 的投递记录
webhook_deliveries_list
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅显示成功或失败的投递",
"enum": [
"succeeded",
"failed"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"webhook_id": {
"type": "string",
"description": "资源的 Webhook"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id",
"webhook_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "投递 ID，例如 whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending、succeeded 或 failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "最后一次尝试的 HTTP 状态"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "最后一次尝试的连接错误"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "前 2,000 个字符"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver.json
重新发送一次投递
webhook_deliveries_redeliver
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"webhook_id": {
"type": "string",
"description": "资源的 Webhook"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"webhook_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "投递 ID，例如 whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending、succeeded 或 failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "最后一次尝试的 HTTP 状态"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "最后一次尝试的连接错误"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "前 2,000 个字符"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/webhooks.json
添加 webhook 端点
webhooks_create
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "接收 POST JSON 的 HTTPS 端点",
"examples": [
"https://example.com/hooks/privatus"
]
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"alert.triggered",
"alert.resolved",
"goal.completed_threshold",
"uptime.down",
"uptime.up",
"export.ready",
"import.completed",
"import.failed",
"site.created",
"site.deleted",
"member.added",
"usage.threshold"
]
},
"description": "要发送的事件"
},
"enabled": {
"type": "boolean",
"description": "发送投递",
"default": true
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"url",
"events",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook ID，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的签名密钥"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/webhooks/:id.json
删除 webhook
webhooks_delete
权限： workspace.manage
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook ID，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的签名密钥"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/webhooks.json
列出 webhook
webhooks_list
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook ID，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的签名密钥"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:workspace_id/webhooks/:id.json
获取 webhook
webhooks_get
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook ID，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的签名密钥"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/webhooks/:id/test.json
发送测试投递
webhooks_test
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id/test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "投递 ID，例如 whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending、succeeded 或 failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "最后一次尝试的 HTTP 状态"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "最后一次尝试的连接错误"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "前 2,000 个字符"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:workspace_id/webhooks/:id.json
更新 webhook（事件、URL、启用状态、轮换密钥）
webhooks_update
权限： workspace.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "HTTPS 端点"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"alert.triggered",
"alert.resolved",
"goal.completed_threshold",
"uptime.down",
"uptime.up",
"export.ready",
"import.completed",
"import.failed",
"site.created",
"site.deleted",
"member.added",
"usage.threshold"
]
},
"description": "要发送的事件"
},
"enabled": {
"type": "boolean",
"description": "发送投递"
},
"rotate_secret": {
"type": "boolean",
"description": "替换签名密钥",
"default": false
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook ID，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的签名密钥"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
事件
GET
/sites/:site_id/events/properties.json
列出过去 30 天内出现过的事件属性键
event_properties_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/events/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "仅显示此原始事件名称上出现过的键"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
PATCH
/sites/:site_id/events/properties.json
重命名或隐藏事件属性键
event_properties_update
权限： sites.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/events/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "属性键（按存储形式），例如 plan"
},
"display_name": {
"type": "string",
"description": "改为显示的标签（留空则移除）"
},
"hidden": {
"type": "boolean",
"description": "在报告中隐藏此键"
},
"export_safe": {
"type": "boolean",
"description": "该键不含个人数据，因此包含在原始导出和数据仓库同步中"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"key",
"site_id"
]
}
响应数据
{
"type": "object"
}
DELETE
/sites/:site_id/events.json
删除事件及其历史（在后台运行，需输入名称确认）
events_delete
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/events.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "要删除的原始事件名称"
},
"confirm": {
"type": "string",
"description": "再次输入事件名称以确认"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"confirm",
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/events.json
列出事件，含完成次数、访问数、转化率以及首次和最近出现时间
events_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/events.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"search": {
"type": "string",
"description": "仅显示名称包含此内容的事件"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
POST
/sites/:site_id/events/merge.json
将多个事件合并为一个显示名称
events_merge
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/events/merge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"names": {
"type": "array",
"items": {
"type": "string"
},
"description": "要合并的原始事件名称"
},
"into": {
"type": "string",
"description": "合并后事件的显示名称",
"examples": [
"Signup"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"names",
"into",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "跟踪器发送的原始事件名称"
},
"display_name": {
"anyOf": [
{
"type": "string",
"description": "报告中显示的名称"
},
{
"type": "null"
}
]
},
"hidden": {
"type": "boolean",
"description": "在报告中隐藏"
},
"currency": {
"anyOf": [
{
"type": "string",
"description": "收入货币"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/events/detail.json
单个事件：图表、属性透视、数值属性聚合、页面和来源
events_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/events/detail.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"name": {
"type": "string",
"description": "显示的事件名称（重命名之后）",
"examples": [
"Signup"
]
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "最多 3 个用于透视的属性键",
"default": []
},
"interval": {
"type": "string",
"description": "图表时间段大小",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"site_id"
]
}
响应数据
{
"type": "object"
}
PATCH
/sites/:site_id/events/settings.json
重命名、隐藏或取消隐藏事件，或设置其货币
events_update
权限： sites.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/events/settings.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "跟踪器发送的原始事件名称",
"examples": [
"signup_click"
]
},
"display_name": {
"type": "string",
"description": "改为显示的名称（留空则取消重命名）"
},
"hidden": {
"type": "boolean",
"description": "在报告中隐藏（数据会保留）"
},
"currency": {
"type": "string",
"description": "此事件收入使用的货币（ISO 4217）"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "跟踪器发送的原始事件名称"
},
"display_name": {
"anyOf": [
{
"type": "string",
"description": "报告中显示的名称"
},
{
"type": "null"
}
]
},
"hidden": {
"type": "boolean",
"description": "在报告中隐藏"
},
"currency": {
"anyOf": [
{
"type": "string",
"description": "收入货币"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
仪表板
GET
/workspaces/:workspace_id/dashboards/:id/cards/:index.json
自定义仪表板某张卡片的数据
dashboards_card
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id/cards/:index.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
},
"index": {
"type": "string",
"description": "资源的 Index"
}
},
"required": [
"workspace_id",
"id",
"index"
]
}
响应数据
{
"type": "object"
}
POST
/workspaces/:workspace_id/dashboards.json
创建自定义仪表板
dashboards_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "仪表板名称",
"examples": [
"Client: Acme"
]
},
"cards": {
"type": "array",
"items": {},
"description": "按顺序排列的卡片（最多 40 张）：[{\"type\": \"metric|chart|breakdown|goal|live|funnel|uptime|vitals\", \"site_id\": \"pa_…\", \"title\": \"optional\", \"params\": {\"period\": \"30d\", \"metric\": \"visitors\", \"dimension\": \"page\", \"funnel_id\": \"fun_…\"}}]。类型不使用的参数会被忽略",
"default": []
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "仪表板 ID，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "按顺序排列的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/dashboards/:id.json
删除自定义仪表板
dashboards_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "仪表板 ID，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "按顺序排列的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/dashboards.json
列出自定义仪表板
dashboards_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "仪表板 ID，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "按顺序排列的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:workspace_id/dashboards/:id.json
获取自定义仪表板及其卡片
dashboards_get
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "仪表板 ID，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "按顺序排列的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:workspace_id/dashboards/:id.json
重命名自定义仪表板或替换其卡片
dashboards_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "新名称（留空则不变）"
},
"cards": {
"type": "array",
"items": {},
"description": "替换所有卡片。按顺序排列的卡片（最多 40 张）：[{\"type\": \"metric|chart|breakdown|goal|live|funnel|uptime|vitals\", \"site_id\": \"pa_…\", \"title\": \"optional\", \"params\": {\"period\": \"30d\", \"metric\": \"visitors\", \"dimension\": \"page\", \"funnel_id\": \"fun_…\"}}]。类型不使用的参数会被忽略"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "仪表板 ID，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "按顺序排列的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
分享
GET
/badge/:site_id.json
公开站点的访客计数徽章（SVG）
badges_get
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/badge/:site_id.json输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
分析
GET
/sites/:site_id/overview.json
站点概览：指标、图表序列、热门面板、实时访客和备注
stats_overview
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/overview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"interval": {
"type": "string",
"description": "图表时间段大小",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"panels": {
"type": "array",
"items": {
"type": "string"
},
"description": "要包含热门值的维度",
"default": [
"channel",
"referrer",
"page",
"entry_page",
"country",
"device",
"browser",
"os",
"utm_campaign",
"event",
"goal"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/experiments.json
实验报告：各变体的转化率、相对对照组的提升和显著性（双比例 z 检验）
experiments_report
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/experiments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"property": {
"type": "string",
"description": "保存变体的事件属性，例如 variant",
"examples": [
"variant"
]
},
"goal_id": {
"type": "string",
"description": "计为转化的目标（goal_…）"
},
"control": {
"type": "string",
"description": "对照变体（如果存在则默认为 \"control\"，否则为访问数最多的变体）"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"property",
"goal_id",
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/insights.json
用自然语言描述相较上一周期的显著变化（变化最大的项目、目标转化变化）
insights_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/insights.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "截至昨天的完整天数，与之前相同天数对比",
"enum": [
"7d",
"14d",
"28d",
"30d"
],
"default": "7d"
},
"limit": {
"type": "integer",
"description": "洞察的最大数量（1 到 20）",
"default": 8
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/journeys.json
旅程：某页面（或任意入口）之后，或某页面或目标之前的前 3 步路径
journeys_explore
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/journeys.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"mode": {
"type": "string",
"description": "forward：起始页面之后的页面，reverse：通向结束页面或目标的页面",
"enum": [
"forward",
"reverse"
],
"default": "forward"
},
"path": {
"type": "string",
"description": "起始页面（forward）或结束页面（reverse）。留空表示任意入口（仅 forward）"
},
"goal_id": {
"type": "string",
"description": "reverse 模式：以此目标（goal_…）而非页面作为终点"
},
"limit": {
"type": "integer",
"description": "每一步显示的页面数（最多 12）",
"default": 6
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/pages/detail.json
页面详情：单个路径的指标、上一页和下一页、来源、性能指标、事件和点击图
pages_detail
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/pages/detail.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"path": {
"type": "string",
"description": "页面路径，例如 /pricing",
"examples": [
"/pricing"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"path",
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/stats/aggregate.json
某个周期的核心指标（可对比）
stats_aggregate
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/stats/aggregate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/breakdown/:dimension.json
某个维度的热门值（页面、来源、国家/地区……）
stats_breakdown
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/breakdown/:dimension.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"dimension": {
"type": "string",
"description": "资源的 Dimension"
},
"limit": {
"type": "integer",
"description": "每页行数（最多 1000）",
"default": 10
},
"page": {
"type": "integer",
"description": "页码",
"default": 1
},
"sort": {
"type": "string",
"description": "排序指标",
"enum": [
"visitors",
"visits",
"pageviews",
"revenue"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"dimension",
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/stats/timeseries.json
用于图表的按时间段划分的指标
stats_timeseries
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/stats/timeseries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"interval": {
"type": "string",
"description": "时间段大小。auto 会根据范围自动选择",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
助手
POST
/sites/:site_id/ask.json
在新对话中提问（计入每月 AI 提问限额）
assistant_ask
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/ask.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "用自然语言描述您的第一个问题",
"examples": [
"How many visitors did we have last week?"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"question",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "对话 ID，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一个问题，已缩短"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后一条消息的时间"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "在此时间之后自动删除（最后一条消息 30 天后）"
},
"messages": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "对话内的消息 ID"
},
"role": {
"type": "string",
"description": "user（问题）或 assistant（答案）"
},
"content": {
"type": "string",
"description": "问题，或 Markdown 格式的答案"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "我是如何得出的：答案背后的确切 API 查询，格式为 [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "答案的图表：{type: line, labels, series, comparison, metric, format} 或 {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "助手建议的目标，需通过 goals_create 确认"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型输入 token 数"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型输出 token 数"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"description": "问题和答案，最早的在前"
}
}
}
DELETE
/sites/:site_id/ask/:id.json
删除一个提问对话及其消息
assistant_conversations_delete
权限： analytics.read
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/ask/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "对话 ID，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一个问题，已缩短"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后一条消息的时间"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "在此时间之后自动删除（最后一条消息 30 天后）"
}
}
}
GET
/sites/:site_id/ask.json
列出您针对某站点的提问对话
assistant_conversations_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/ask.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "对话 ID，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一个问题，已缩短"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后一条消息的时间"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "在此时间之后自动删除（最后一条消息 30 天后）"
}
}
}
}
GET
/sites/:site_id/ask/:id.json
一个提问对话：问题、答案、其背后的查询和图表
assistant_conversations_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/ask/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "对话 ID，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一个问题，已缩短"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后一条消息的时间"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "在此时间之后自动删除（最后一条消息 30 天后）"
},
"messages": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "对话内的消息 ID"
},
"role": {
"type": "string",
"description": "user（问题）或 assistant（答案）"
},
"content": {
"type": "string",
"description": "问题，或 Markdown 格式的答案"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "我是如何得出的：答案背后的确切 API 查询，格式为 [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "答案的图表：{type: line, labels, series, comparison, metric, format} 或 {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "助手建议的目标，需通过 goals_create 确认"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型输入 token 数"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型输出 token 数"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"description": "问题和答案，最早的在前"
}
}
}
POST
/sites/:site_id/ask/:ask_conversation_id/messages.json
在对话中继续追问（计入每月 AI 提问限额）。返回答案。
assistant_ask_followup
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/ask/:ask_conversation_id/messages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "用自然语言描述您的问题",
"examples": [
"Which pages had the most visitors last week?"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"ask_conversation_id": {
"type": "string",
"description": "资源的 Ask conversation"
}
},
"required": [
"question",
"site_id",
"ask_conversation_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "对话内的消息 ID"
},
"role": {
"type": "string",
"description": "user（问题）或 assistant（答案）"
},
"content": {
"type": "string",
"description": "问题，或 Markdown 格式的答案"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "我是如何得出的：答案背后的确切 API 查询，格式为 [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "答案的图表：{type: line, labels, series, comparison, metric, format} 或 {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "助手建议的目标，需通过 goals_create 确认"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型输入 token 数"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型输出 token 数"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
备注
POST
/sites/:site_id/notes.json
为站点添加备注（发布 webhook 请使用来源 "deploy"）
notes_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "备注的日期（站点时区）。默认为今天"
},
"end_date": {
"type": "string",
"format": "date",
"description": "最后一天，用于日期范围"
},
"title": {
"type": "string",
"description": "显示在图表上的简短标题",
"examples": [
"Launched new pricing"
]
},
"body": {
"type": "string",
"description": "详情（Markdown）"
},
"url": {
"type": "string",
"description": "链接，例如 PR 或更新日志"
},
"color": {
"type": "string",
"description": "标记颜色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"source": {
"type": "string",
"description": "manual，或用于发布 webhook 的 deploy",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
],
"default": "manual"
},
"version": {
"type": "string",
"description": "部署：发布版本或提交，用于默认标题"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/notes/:id.json
删除备注
notes_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/notes.json
列出站点的备注（包括工作区范围的备注）
notes_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "仅显示此日期及之后的备注"
},
"to": {
"type": "string",
"format": "date",
"description": "仅显示此日期及之前的备注"
},
"source": {
"type": "string",
"description": "仅显示来自此来源的备注",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
]
},
"query": {
"type": "string",
"description": "搜索标题、正文和链接"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/notes/:id.json
获取备注
notes_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/notes/:id.json
编辑备注
notes_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "备注的日期"
},
"end_date": {
"type": "string",
"format": "date",
"description": "最后一天，用于日期范围"
},
"title": {
"type": "string",
"description": "显示在图表上的简短标题"
},
"body": {
"type": "string",
"description": "详情（Markdown）"
},
"url": {
"type": "string",
"description": "链接"
},
"color": {
"type": "string",
"description": "标记颜色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/notes.json
添加工作区范围的备注（在每个站点上显示）
workspace_notes_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "备注的日期（站点时区）。默认为今天"
},
"end_date": {
"type": "string",
"format": "date",
"description": "最后一天，用于日期范围"
},
"title": {
"type": "string",
"description": "显示在图表上的简短标题",
"examples": [
"Launched new pricing"
]
},
"body": {
"type": "string",
"description": "详情（Markdown）"
},
"url": {
"type": "string",
"description": "链接，例如 PR 或更新日志"
},
"color": {
"type": "string",
"description": "标记颜色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"source": {
"type": "string",
"description": "manual，或用于发布 webhook 的 deploy",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
],
"default": "manual"
},
"version": {
"type": "string",
"description": "部署：发布版本或提交，用于默认标题"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/notes/:id.json
删除工作区备注
workspace_notes_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/notes.json
列出整个工作区的备注
workspace_notes_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "仅显示此日期及之后的备注"
},
"to": {
"type": "string",
"format": "date",
"description": "仅显示此日期及之前的备注"
},
"source": {
"type": "string",
"description": "仅显示来自此来源的备注",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
]
},
"query": {
"type": "string",
"description": "搜索标题、正文和链接"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/workspaces/:workspace_id/notes/:id.json
编辑工作区备注
workspace_notes_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "备注的日期"
},
"end_date": {
"type": "string",
"format": "date",
"description": "最后一天，用于日期范围"
},
"title": {
"type": "string",
"description": "显示在图表上的简短标题"
},
"body": {
"type": "string",
"description": "详情（Markdown）"
},
"url": {
"type": "string",
"description": "链接"
},
"color": {
"type": "string",
"description": "标记颜色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "备注 ID，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点，工作区范围的备注为 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
套餐
GET
/plans.json
列出套餐、价格和限额
plans_list
权限： public
示例
curl https://privatusanalytics.com/plans.json输入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": []
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"events": {
"anyOf": [
{
"type": "integer",
"description": "每月包含的事件数（仅免费套餐）"
},
{
"type": "null"
}
]
},
"badge_bonus": {
"anyOf": [
{
"type": "integer",
"description": "展示徽章可额外获得的每月事件数（免费套餐）"
},
{
"type": "null"
}
]
},
"limits": {
"type": "object",
"description": "套餐限额。Null 表示无限制"
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"events": {
"type": "integer",
"description": "包含的每月事件数"
},
"monthly": {
"type": "integer",
"description": "每月美元金额，按月计费"
},
"yearly": {
"type": "integer",
"description": "每年美元金额，按年计费（免费 2 个月）"
},
"monthly_price_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle 价格 ID（按月）"
},
{
"type": "null"
}
]
},
"yearly_price_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle 价格 ID（按年）"
},
{
"type": "null"
}
]
}
}
},
"description": "按每月事件数划分的价格阶梯"
},
"contact_sales": {
"type": "boolean",
"description": "按合同定价"
}
}
}
}
实时
GET
/sites/:site_id/live.json
实时访客、活动流以及当前热门内容（过去 30 分钟）
live_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/live.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"feed": {
"type": "string",
"description": "活动流：所有请求、浏览量或自定义事件",
"enum": [
"all",
"pageviews",
"events"
],
"default": "all"
},
"limit": {
"type": "integer",
"description": "活动流条目数（最多 100）",
"default": 50
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/live/wallboard.json
一个或多个站点的大屏卡片（实时和今日）
live_wallboard
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/live/wallboard.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要轮换显示的站点 ID（默认为此站点）",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "每个站点在屏幕上停留的秒数（5-300）",
"default": 20
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/wallboard/:token.json
凭大屏令牌查看大屏（无需登录）
live_public_wallboard
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/wallboard/:token.json输入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要轮换显示的站点 ID（默认为此站点）",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "每个站点在屏幕上停留的秒数（5-300）",
"default": 20
},
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object"
}
POST
/sites/:site_id/live/wallboard/links.json
创建大屏链接（只读，可撤销）
wallboard_links_create
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "标签，例如 Office TV"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要额外轮换显示的站点（始终包含此站点）",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "轮换时每个站点的秒数（5-300）",
"default": 20
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "在此时间之后失效"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "在电视上打开此链接。无需登录"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "轮换显示的站点"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/live/wallboard/links/:id.json
撤销大屏链接
wallboard_links_delete
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/live/wallboard/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "在电视上打开此链接。无需登录"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "轮换显示的站点"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/live/wallboard/links.json
列出站点的大屏链接
wallboard_links_list
权限： sites.manage
示例
curl https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "在电视上打开此链接。无需登录"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "轮换显示的站点"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
审计日志
GET
/workspaces/:workspace_id/audit_log.json
列出审计日志条目（添加 .csv 可导出）
audit_logs_get
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/audit_log.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"actor": {
"type": "string",
"description": "仅显示此成员（邮箱）所做的更改"
},
"item_type": {
"type": "string",
"description": "仅显示此类记录，例如 Site"
},
"event": {
"type": "string",
"description": "仅显示此操作",
"enum": [
"create",
"update",
"destroy"
]
},
"from": {
"type": "string",
"format": "date",
"description": "起始日期（含）"
},
"to": {
"type": "string",
"format": "date",
"description": "结束日期（含）"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "时间"
},
"event": {
"type": "string",
"description": "create、update 或 destroy"
},
"item_type": {
"type": "string",
"description": "记录类型，例如 Site"
},
"item_id": {
"type": "string",
"format": "uuid"
},
"target": {
"type": "string",
"description": "记录，已知时使用名称"
},
"actor_email": {
"anyOf": [
{
"type": "string",
"description": "进行更改的成员"
},
{
"type": "null"
}
]
},
"actor_name": {
"type": "string"
},
"token_name": {
"anyOf": [
{
"type": "string",
"description": "使用的 API 令牌（如有）"
},
{
"type": "null"
}
]
},
"changes": {
"type": "object",
"description": "已更改的字段：{ field: [before, after] }"
},
"ip": {
"anyOf": [
{
"type": "string",
"description": "该成员的 IP 地址"
},
{
"type": "null"
}
]
}
}
}
}
导入
GET
/sites/:site_id/imports/google/properties.json
列出可导入的 Google Analytics 4 属性
imports_google_properties
权限： sites.manage
示例
curl https://privatusanalytics.com/sites/:site_id/imports/google/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
POST
/sites/:site_id/imports.json
开始导入（GA4 属性或 CSV 上传）
imports_create
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/imports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "ga4（Google Analytics 4 API）或您上传其 CSV 导出的工具",
"enum": [
"ga4",
"universal_analytics",
"fathom",
"simple_analytics",
"plausible",
"matomo",
"umami",
"clicky"
]
},
"property_id": {
"type": "string",
"description": "GA4 属性，例如 properties/123（参见 imports_google_properties）。ga4 必填",
"examples": [
"properties/123456789"
]
},
"date_from": {
"type": "string",
"format": "date",
"description": "要导入的第一天。ga4 必填。对于没有日期列的 CSV 文件，每一行都记为这一天"
},
"date_to": {
"type": "string",
"format": "date",
"description": "要导入的最后一天（ga4 默认为您首个已跟踪事件的前一天，或昨天）"
},
"file": {
"type": "string",
"format": "binary",
"description": "CSV 导出（multipart 上传，最大 50 MB）。CSV 来源必填"
},
"dimension": {
"type": "string",
"description": "CSV 行所细分的内容（覆盖自动检测，Matomo \"Label\" 导出需要）",
"enum": [
"total",
"page",
"source",
"country",
"device",
"browser",
"os"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"source",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导入 ID"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的最后一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已存储的每日行数"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导入失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/imports/:id.json
删除导入及其所有导入的数据
imports_delete
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/imports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导入 ID"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的最后一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已存储的每日行数"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导入失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/imports.json
列出站点的导入
imports_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/imports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅显示此状态的导入",
"enum": [
"queued",
"running",
"complete",
"failed"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导入 ID"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的最后一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已存储的每日行数"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导入失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/imports/:id.json
获取导入及其状态
imports_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/imports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导入 ID"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "导入的最后一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已存储的每日行数"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导入失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
导出
POST
/workspaces/:workspace_id/exports.json
将导出加入队列（在后台生成）
exports_create
权限： analytics.export
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "要导出的站点（pa_…）",
"examples": [
"pa_7Q2K9XH3AB"
]
},
"kind": {
"type": "string",
"description": "aggregated：按时间段和维度的指标。pageviews/events/raw：每次请求一行（Pro 及以上）。imported：导入的每日统计。dashboard：概览面板的 ZIP",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
],
"default": "aggregated"
},
"file_format": {
"type": "string",
"description": "csv、json 或 xlsx（aggregated、pageviews、events、imported），csv 或 ndjson（raw），zip（dashboard）",
"enum": [
"csv",
"json",
"xlsx",
"ndjson",
"zip"
],
"default": "csv"
},
"from": {
"type": "string",
"format": "date",
"description": "第一天，使用导出时区",
"examples": [
"2026-09-01"
]
},
"to": {
"type": "string",
"format": "date",
"description": "最后一天，含当天（最多 400 天，raw 为 93 天）",
"examples": [
"2026-09-28"
]
},
"timezone": {
"type": "string",
"description": "日期和分组使用的时区，例如 America/New_York（默认：站点时区）"
},
"grouping": {
"type": "string",
"description": "聚合导出的时间段",
"enum": [
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "day"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "聚合导出按其分组的访问维度（最多 6 个），例如 country、channel、entry_page。对于 imported 导出：要包含的导入维度",
"default": []
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "聚合导出的指标（默认全部）：visitors、visits、pageviews、bounce_rate、visit_duration、views_per_visit、revenue",
"default": []
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "pageviews/events/raw 导出的列（默认为除 visit_id、vital_value、selector 之外的全部）：occurred_at, kind, name, visit_id, hostname, path, referrer_host, referrer_path, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, ref, paid_click, country, language, device, browser, browser_major, os, os_major, screen_bucket, engaged_ms, scroll_depth, revenue_minor, currency, vital_value, selector, props",
"default": []
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件，格式与统计 API 相同：[[\"dimension\",\"operator\",\"value\"], …]",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"site_id",
"from",
"to",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导出 ID，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "导出的站点（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "导出定义（日期、时区、分组、维度、指标、字段、筛选条件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已写入的行数"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导出失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "文件被删除的时间"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "返回短期有效签名文件链接的路径（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/exports/:id.json
删除导出及其文件
exports_delete
权限： analytics.export
示例
curl -X DELETE https://privatusanalytics.com/exports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导出 ID，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "导出的站点（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "导出定义（日期、时区、分组、维度、指标、字段、筛选条件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已写入的行数"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导出失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "文件被删除的时间"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "返回短期有效签名文件链接的路径（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/exports/:id/download.json
获取文件的签名链接（有效期 10 分钟）
exports_download
权限： analytics.export
示例
curl https://privatusanalytics.com/exports/:id/download.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object"
}
GET
/workspaces/:workspace_id/exports.json
列出导出（作业队列）
exports_list
权限： analytics.export
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "仅显示此站点的导出（pa_…）"
},
"status": {
"type": "string",
"description": "仅显示此状态的导出",
"enum": [
"queued",
"running",
"complete",
"failed",
"expired"
]
},
"kind": {
"type": "string",
"description": "仅显示此类型的导出",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导出 ID，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "导出的站点（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "导出定义（日期、时区、分组、维度、指标、字段、筛选条件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已写入的行数"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导出失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "文件被删除的时间"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "返回短期有效签名文件链接的路径（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/exports/preview.json
预览导出：前 20 行和预估行数
exports_preview
权限： analytics.export
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "要导出的站点（pa_…）",
"examples": [
"pa_7Q2K9XH3AB"
]
},
"kind": {
"type": "string",
"description": "aggregated：按时间段和维度的指标。pageviews/events/raw：每次请求一行（Pro 及以上）。imported：导入的每日统计。dashboard：概览面板的 ZIP",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
],
"default": "aggregated"
},
"file_format": {
"type": "string",
"description": "csv、json 或 xlsx（aggregated、pageviews、events、imported），csv 或 ndjson（raw），zip（dashboard）",
"enum": [
"csv",
"json",
"xlsx",
"ndjson",
"zip"
],
"default": "csv"
},
"from": {
"type": "string",
"format": "date",
"description": "第一天，使用导出时区",
"examples": [
"2026-09-01"
]
},
"to": {
"type": "string",
"format": "date",
"description": "最后一天，含当天（最多 400 天，raw 为 93 天）",
"examples": [
"2026-09-28"
]
},
"timezone": {
"type": "string",
"description": "日期和分组使用的时区，例如 America/New_York（默认：站点时区）"
},
"grouping": {
"type": "string",
"description": "聚合导出的时间段",
"enum": [
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "day"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "聚合导出按其分组的访问维度（最多 6 个），例如 country、channel、entry_page。对于 imported 导出：要包含的导入维度",
"default": []
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "聚合导出的指标（默认全部）：visitors、visits、pageviews、bounce_rate、visit_duration、views_per_visit、revenue",
"default": []
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "pageviews/events/raw 导出的列（默认为除 visit_id、vital_value、selector 之外的全部）：occurred_at, kind, name, visit_id, hostname, path, referrer_host, referrer_path, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, ref, paid_click, country, language, device, browser, browser_major, os, os_major, screen_bucket, engaged_ms, scroll_depth, revenue_minor, currency, vital_value, selector, props",
"default": []
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件，格式与统计 API 相同：[[\"dimension\",\"operator\",\"value\"], …]",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"site_id",
"from",
"to",
"workspace_id"
]
}
响应数据
{
"type": "object"
}
GET
/exports/:id.json
获取导出及其状态
exports_get
权限： analytics.export
示例
curl https://privatusanalytics.com/exports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "导出 ID，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "导出的站点（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "导出定义（日期、时区、分组、维度、指标、字段、筛选条件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已写入的行数"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "导出失败的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "文件被删除的时间"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "返回短期有效签名文件链接的路径（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
工作区
GET
/workspaces/:workspace_id/white_label.json
获取白标品牌
white_label_get
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"brand_name": {
"anyOf": [
{
"type": "string",
"description": "代替 Privatus Analytics 显示的名称"
},
{
"type": "null"
}
]
},
"brand_logo_url": {
"anyOf": [
{
"type": "string",
"description": "徽标图片 URL"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string",
"description": "强调色"
},
{
"type": "null"
}
]
},
"hide_branding": {
"type": "boolean",
"description": "已隐藏 Privatus Analytics 品牌标识"
},
"available": {
"type": "boolean",
"description": "该套餐包含白标"
},
"active": {
"type": "boolean",
"description": "当前已应用该品牌"
}
}
}
PATCH
/workspaces/:workspace_id/white_label.json
为共享仪表板和邮件报告设置白标品牌（Business）
white_label_update
权限： workspace.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"brand_name": {
"type": "string",
"description": "代替 Privatus Analytics 显示的名称（留空则移除）"
},
"brand_logo_url": {
"type": "string",
"description": "徽标图片的 https URL（留空则移除）"
},
"brand_color": {
"type": "string",
"description": "强调色，例如 #06755b"
},
"hide_branding": {
"type": "boolean",
"description": "在共享仪表板和邮件报告中隐藏“Privatus Analytics”"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"brand_name": {
"anyOf": [
{
"type": "string",
"description": "代替 Privatus Analytics 显示的名称"
},
{
"type": "null"
}
]
},
"brand_logo_url": {
"anyOf": [
{
"type": "string",
"description": "徽标图片 URL"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string",
"description": "强调色"
},
{
"type": "null"
}
]
},
"hide_branding": {
"type": "boolean",
"description": "已隐藏 Privatus Analytics 品牌标识"
},
"available": {
"type": "boolean",
"description": "该套餐包含白标"
},
"active": {
"type": "boolean",
"description": "当前已应用该品牌"
}
}
}
GET
/workspaces/:workspace_id/security.json
获取工作区安全设置
workspace_security_get
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/security.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"enforce_2fa": {
"type": "boolean",
"description": "成员必须设置双重验证"
},
"login_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "允许的登录方式"
},
"session_ttl_hours": {
"anyOf": [
{
"type": "integer",
"description": "会话有效期（null = 无）"
},
{
"type": "null"
}
]
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "允许的 IP/CIDR（空 = 任何地方）"
},
"support_access_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Privatus Analytics 支持团队可查看该工作区直到"
},
{
"type": "null"
}
]
}
}
}
PATCH
/workspaces/:workspace_id/security.json
更新工作区安全设置（双重验证、登录方式、会话时长、IP 白名单、支持访问）
workspace_security_update
权限： workspace.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/security.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"enforce_2fa": {
"type": "boolean",
"description": "要求成员设置双重验证"
},
"login_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"password",
"magic_link",
"passkey",
"google",
"github",
"sso"
]
},
"description": "允许的登录方式"
},
"session_ttl_hours": {
"type": "integer",
"description": "在这么多小时后让成员退出登录（0 = 不限制）"
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "仅允许来自这些 IP/CIDR 的应用和 API 访问（Business）。留空 = 任何地方"
},
"support_access": {
"type": "boolean",
"description": "允许 Privatus Analytics 支持团队查看该工作区 7 天"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"enforce_2fa": {
"type": "boolean",
"description": "成员必须设置双重验证"
},
"login_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "允许的登录方式"
},
"session_ttl_hours": {
"anyOf": [
{
"type": "integer",
"description": "会话有效期（null = 无）"
},
{
"type": "null"
}
]
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "允许的 IP/CIDR（空 = 任何地方）"
},
"support_access_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Privatus Analytics 支持团队可查看该工作区直到"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces.json
创建工作区（您将成为所有者）
workspaces_create
权限： member
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/workspaces.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "工作区名称",
"examples": [
"Acme Inc"
]
},
"timezone": {
"type": "string",
"description": "默认报告时区（默认为用户的时区）"
},
"currency": {
"type": "string",
"description": "默认货币（ISO 4217）",
"default": "USD"
},
"how_heard": {
"type": "string",
"description": "您是如何了解我们的"
}
},
"required": [
"name"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "默认报告时区"
},
"currency": {
"type": "string",
"description": "默认货币"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "套餐每月包含的事件数"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作区中的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:id.json
删除工作区及其所有站点（仅所有者可操作，会取消所有订阅）
workspaces_delete
权限： workspace.manage
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"confirm": {
"type": "string",
"description": "输入工作区名称以确认"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"confirm",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "默认报告时区"
},
"currency": {
"type": "string",
"description": "默认货币"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "套餐每月包含的事件数"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作区中的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces.json
列出您的工作区
workspaces_list
权限： member
示例
curl https://privatusanalytics.com/workspaces.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": []
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "默认报告时区"
},
"currency": {
"type": "string",
"description": "默认货币"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "套餐每月包含的事件数"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作区中的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:id.json
获取工作区
workspaces_get
权限： member
示例
curl https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "默认报告时区"
},
"currency": {
"type": "string",
"description": "默认货币"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "套餐每月包含的事件数"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作区中的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:id.json
更新工作区设置
workspaces_update
权限： workspace.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "工作区名称"
},
"timezone": {
"type": "string",
"description": "默认报告时区"
},
"currency": {
"type": "string",
"description": "默认货币（ISO 4217）"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "默认报告时区"
},
"currency": {
"type": "string",
"description": "默认货币"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "套餐每月包含的事件数"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作区中的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
帮助与反馈
POST
/help.json
向 Privatus Analytics 团队发送问题或反馈
support_message_send
消息会通过电子邮件发送给团队，并附上您的账户、工作区和套餐详情。回复和回执会发送到您的账户邮箱。每天最多 10 条消息。
权限： member
示例
curl -X POST https://privatusanalytics.com/help.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "消息的主题（最多 150 个字符）",
"examples": [
"Funnel shows no data"
]
},
"message": {
"type": "string",
"description": "您的问题或反馈（10 到 5,000 个字符）"
}
},
"required": [
"subject",
"message"
]
}
响应数据
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受时始终为 true"
},
"message": {
"type": "string",
"description": "接下来会发生什么"
}
}
}
性能
GET
/sites/:site_id/performance.json
网页性能指标：p75 评分卡、每日趋势以及按页面、设备、浏览器和国家/地区的细分
performance_report
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/performance.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"metric": {
"type": "string",
"description": "用于趋势和细分的指标",
"enum": [
"LCP",
"INP",
"CLS",
"FCP",
"TTFB"
],
"default": "LCP"
},
"limit": {
"type": "integer",
"description": "每个细分的行数（最多 100）",
"default": 10
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
成员
POST
/workspaces/:workspace_id/invitations.json
通过邮件邀请他人
invitations_create
权限： members.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "要邀请的邮箱地址"
},
"role": {
"type": "string",
"description": "新成员的角色（custom 需要 custom_role_id）",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
],
"default": "viewer"
},
"custom_role_id": {
"type": "string",
"description": "自定义角色 ID（Business）"
},
"all_sites": {
"type": "boolean",
"description": "访问所有站点，包括将来添加的",
"default": true
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 为 false 时的站点 ID（pa_…）",
"default": []
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"emails",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/invitations/:id.json
撤销待处理的邀请
invitations_delete
权限： members.manage
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/invitations/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/invitations.json
列出待处理的邀请
invitations_list
权限： members.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
DELETE
/workspaces/:workspace_id/members/:id.json
移除成员（或退出工作区）
members_delete
权限： member
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成员 ID（用于更新或移除该成员）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自定义角色名称"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "访问所有站点"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 为 false 时的站点 ID"
},
"two_factor": {
"type": "boolean",
"description": "已启用双重验证或通行密钥"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入时间"
}
}
}
GET
/workspaces/:workspace_id/members.json
列出工作区成员
members_list
权限： member
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/members.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "按姓名或邮箱筛选"
},
"role": {
"type": "string",
"description": "仅显示此角色的成员",
"enum": [
"owner",
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成员 ID（用于更新或移除该成员）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自定义角色名称"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "访问所有站点"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 为 false 时的站点 ID"
},
"two_factor": {
"type": "boolean",
"description": "已启用双重验证或通行密钥"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入时间"
}
}
}
}
PATCH
/workspaces/:workspace_id/members/:id.json
更改成员的角色或站点访问权限
members_update
权限： members.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "新角色（custom 需要 custom_role_id）",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
]
},
"custom_role_id": {
"type": "string",
"description": "自定义角色 ID（Business）"
},
"all_sites": {
"type": "boolean",
"description": "访问所有站点，包括将来添加的"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 为 false 时的站点 ID（pa_…）"
},
"include_future_sites": {
"type": "boolean",
"description": "同时授予之后添加的站点"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成员 ID（用于更新或移除该成员）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自定义角色名称"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "访问所有站点"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 为 false 时的站点 ID"
},
"two_factor": {
"type": "boolean",
"description": "已启用双重验证或通行密钥"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入时间"
}
}
}
POST
/workspaces/:workspace_id/ownership_transfer.json
将工作区所有权转让给其他成员（仅所有者可操作，您将成为管理员）
ownership_transfers_create
权限： member
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/ownership_transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"description": "新所有者的成员 ID"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"membership_id",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成员 ID（用于更新或移除该成员）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自定义角色名称"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "访问所有站点"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 为 false 时的站点 ID"
},
"two_factor": {
"type": "boolean",
"description": "已启用双重验证或通行密钥"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入时间"
}
}
}
搜索
GET
/sites/:site_id/search.json
搜索报告：点击、展示、点击率、排名、热门查询词/页面、落地页和机会
search_report
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/search.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"provider": {
"type": "string",
"description": "google（Search Console）或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"limit": {
"type": "integer",
"description": "每个表格的行数（最多 100）",
"default": 25
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
POST
/sites/:site_id/search/connections.json
连接 Search Console 属性或 Bing 站点
search_connect
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/search/connections.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"property": {
"type": "string",
"description": "Search Console 属性（例如 sc-domain:example.com）或 Bing 站点 URL",
"examples": [
"sc-domain:example.com"
]
},
"bing_api_key": {
"type": "string",
"description": "您自己的 Bing Webmaster Tools API 密钥（Settings > API access）。provider 为 bing 时必填。加密存储，绝不返回。"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"property",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing"
},
"property": {
"type": "string",
"description": "Search Console 属性或 Bing 站点 URL"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/search/connections/:provider.json
断开 Search Console 或 Bing 并删除其数据
search_disconnect
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/search/connections/:provider.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"provider": {
"type": "string",
"description": "资源的 Provider"
}
},
"required": [
"site_id",
"provider"
]
}
响应数据
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing"
},
"property": {
"type": "string",
"description": "Search Console 属性或 Bing 站点 URL"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/search/properties.json
列出您可以连接的属性（Search Console 需要在浏览器中进行 Google 授权）
search_properties
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/search/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"bing_api_key": {
"type": "string",
"description": "您自己的 Bing Webmaster Tools API 密钥（Settings > API access）。provider 为 bing 时必填。仅用于列出它能看到的站点。"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
POST
/sites/:site_id/search/sync.json
立即导入搜索数据
search_sync
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/search/sync.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing"
},
"property": {
"type": "string",
"description": "Search Console 属性或 Bing 站点 URL"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
数据仓库同步
POST
/workspaces/:workspace_id/warehouses.json
添加数据仓库目的地
warehouse_destinations_create
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "显示名称，例如 Data lake"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要发送的站点（pa_…）。留空则发送所有站点"
},
"bucket": {
"type": "string",
"description": "s3：存储桶名称"
},
"region": {
"type": "string",
"description": "s3：区域，例如 us-east-1（R2 使用 auto）"
},
"prefix": {
"type": "string",
"description": "s3/azure：路径前缀，例如 privatus/events"
},
"endpoint": {
"type": "string",
"description": "s3：兼容 S3 存储的 https 端点（GCS 互操作、R2、MinIO）"
},
"access_key_id": {
"type": "string",
"description": "s3：访问密钥 ID"
},
"secret_access_key": {
"type": "string",
"description": "s3：秘密访问密钥（只写）"
},
"service_account_json": {
"type": "string",
"description": "bigquery：具有 BigQuery Data Editor 权限的服务账号 JSON 密钥（只写）"
},
"project_id": {
"type": "string",
"description": "bigquery：项目 ID（默认：取自密钥）"
},
"dataset": {
"type": "string",
"description": "bigquery：数据集 ID"
},
"table": {
"type": "string",
"description": "bigquery/snowflake：表名（列：schema v1）"
},
"account": {
"type": "string",
"description": "snowflake：账户标识符，例如 xy12345.us-east-1 或 myorg-myaccount"
},
"user": {
"type": "string",
"description": "snowflake：使用密钥对认证的用户"
},
"private_key": {
"type": "string",
"description": "snowflake：PEM RSA 私钥（只写）"
},
"database": {
"type": "string",
"description": "snowflake：数据库"
},
"schema": {
"type": "string",
"description": "snowflake：schema"
},
"warehouse": {
"type": "string",
"description": "snowflake：虚拟仓库"
},
"role": {
"type": "string",
"description": "snowflake：角色（可选）"
},
"sas_url": {
"type": "string",
"description": "azure：具有创建/写入权限的容器 SAS URL（只写）"
},
"kind": {
"type": "string",
"description": "s3（也适用于 GCS/R2/MinIO）、bigquery、snowflake 或 azure",
"enum": [
"s3",
"bigquery",
"snowflake",
"azure"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"kind",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 ID，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "数据去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table 或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填写的设置名称（绝不返回其值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "发送的站点（pa_…）。留空表示所有站点"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，发送前一个 UTC 日"
},
"schema_version": {
"type": "string",
"description": "发送的行 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/warehouses/:id.json
删除数据仓库目的地
warehouse_destinations_delete
权限： workspace.manage
示例
curl -X DELETE https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 ID，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "数据去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table 或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填写的设置名称（绝不返回其值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "发送的站点（pa_…）。留空表示所有站点"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，发送前一个 UTC 日"
},
"schema_version": {
"type": "string",
"description": "发送的行 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/warehouses.json
列出数据仓库目的地
warehouse_destinations_list
权限： workspace.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "仅显示此类型的目的地",
"enum": [
"s3",
"bigquery",
"snowflake",
"azure"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 ID，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "数据去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table 或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填写的设置名称（绝不返回其值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "发送的站点（pa_…）。留空表示所有站点"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，发送前一个 UTC 日"
},
"schema_version": {
"type": "string",
"description": "发送的行 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/warehouses/:id.json
获取数据仓库目的地（不含密钥）
warehouse_destinations_get
权限： workspace.manage
示例
curl https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 ID，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "数据去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table 或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填写的设置名称（绝不返回其值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "发送的站点（pa_…）。留空表示所有站点"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，发送前一个 UTC 日"
},
"schema_version": {
"type": "string",
"description": "发送的行 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/warehouses/:id/sync.json
将某一天的同步加入队列并立即执行
warehouse_destinations_sync
权限： workspace.manage
示例
curl -X POST https://privatusanalytics.com/warehouses/:id/sync.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "要发送的 UTC 日期，例如 2026-09-28（默认：昨天）"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 ID，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "数据去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table 或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填写的设置名称（绝不返回其值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "发送的站点（pa_…）。留空表示所有站点"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，发送前一个 UTC 日"
},
"schema_version": {
"type": "string",
"description": "发送的行 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/warehouses/:id.json
更新数据仓库目的地（留空的密钥会保留）
warehouse_destinations_update
权限： workspace.manage
示例
curl -X PATCH https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "显示名称，例如 Data lake"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要发送的站点（pa_…）。留空则发送所有站点"
},
"bucket": {
"type": "string",
"description": "s3：存储桶名称"
},
"region": {
"type": "string",
"description": "s3：区域，例如 us-east-1（R2 使用 auto）"
},
"prefix": {
"type": "string",
"description": "s3/azure：路径前缀，例如 privatus/events"
},
"endpoint": {
"type": "string",
"description": "s3：兼容 S3 存储的 https 端点（GCS 互操作、R2、MinIO）"
},
"access_key_id": {
"type": "string",
"description": "s3：访问密钥 ID"
},
"secret_access_key": {
"type": "string",
"description": "s3：秘密访问密钥（只写）"
},
"service_account_json": {
"type": "string",
"description": "bigquery：具有 BigQuery Data Editor 权限的服务账号 JSON 密钥（只写）"
},
"project_id": {
"type": "string",
"description": "bigquery：项目 ID（默认：取自密钥）"
},
"dataset": {
"type": "string",
"description": "bigquery：数据集 ID"
},
"table": {
"type": "string",
"description": "bigquery/snowflake：表名（列：schema v1）"
},
"account": {
"type": "string",
"description": "snowflake：账户标识符，例如 xy12345.us-east-1 或 myorg-myaccount"
},
"user": {
"type": "string",
"description": "snowflake：使用密钥对认证的用户"
},
"private_key": {
"type": "string",
"description": "snowflake：PEM RSA 私钥（只写）"
},
"database": {
"type": "string",
"description": "snowflake：数据库"
},
"schema": {
"type": "string",
"description": "snowflake：schema"
},
"warehouse": {
"type": "string",
"description": "snowflake：虚拟仓库"
},
"role": {
"type": "string",
"description": "snowflake：角色（可选）"
},
"sas_url": {
"type": "string",
"description": "azure：具有创建/写入权限的容器 SAS URL（只写）"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 ID，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "数据去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table 或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填写的设置名称（绝不返回其值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "发送的站点（pa_…）。留空表示所有站点"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，发送前一个 UTC 日"
},
"schema_version": {
"type": "string",
"description": "发送的行 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
数据收集
POST
/api/logs.json
发送服务器访问日志用于 AI 爬虫报告（JSON {lines: [...]} 或合并格式日志文本，以站点采集密钥作为 Bearer 令牌）
crawler_logs_create
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/api/logs.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ts": {
"type": "string"
},
"path": {
"type": "string",
"default": "/"
},
"status": {
"type": "integer"
},
"user_agent": {
"type": "string",
"default": ""
}
}
},
"description": "日志行：[{ts, path, status, user_agent}]（最多 1000 条）"
}
},
"required": [
"lines"
]
}
响应数据
{
"type": "object"
}
POST
/api/event.json
收集浏览器请求（由 /js/pa.js 使用）
ingest_event
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/api/event.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site": {
"type": "string",
"description": "站点 ID（pa_…）"
},
"type": {
"type": "string",
"description": "请求类型",
"enum": [
"pageview",
"event",
"engagement",
"vital",
"click"
]
},
"url": {
"type": "string",
"description": "完整页面 URL"
},
"referrer": {
"type": "string",
"description": "document.referrer"
},
"name": {
"type": "string",
"description": "事件名称（type=event）或性能指标名称"
},
"props": {
"type": "object",
"additionalProperties": true,
"description": "事件属性：最多 30 个字符串/数字/布尔值",
"default": {}
},
"screen_width": {
"type": "integer",
"description": "屏幕宽度（像素）"
},
"language": {
"type": "string",
"description": "navigator.language"
},
"engaged_ms": {
"type": "integer",
"description": "页面上的可见时间（互动）"
},
"scroll_depth": {
"type": "integer",
"description": "最大滚动深度百分比（互动）"
},
"value": {
"type": "number",
"description": "网页性能指标值（type=vital）"
},
"selector": {
"type": "string",
"description": "被点击元素的选择器（type=click）"
},
"hash_mode": {
"type": "boolean",
"description": "保留 #fragment（使用哈希路由的站点）",
"default": false
},
"dnt": {
"type": "boolean",
"description": "已开启“请勿跟踪”",
"default": false
},
"gpc": {
"type": "boolean",
"description": "已开启全局隐私控制",
"default": false
},
"interacted": {
"type": "boolean",
"description": "页面上出现过可信输入（指针、按键、触摸或滚轮）时为 1，否则为 0。不含坐标或时间"
},
"revenue": {
"type": "number",
"description": "收入，以主要货币单位计，例如 49.99"
},
"currency": {
"type": "string",
"description": "收入的 ISO 4217 货币"
}
},
"required": [
"site",
"type",
"url"
]
}
响应数据
{
"type": "object"
}
POST
/api/events.json
使用站点采集密钥收集服务器端事件
ingest_events
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/api/events.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "最多 100 个事件"
}
},
"required": [
"events"
]
}
响应数据
{
"type": "object"
}
GET
/api/pixel.json
在没有 JavaScript 的情况下收集浏览量（1×1 GIF）
ingest_pixel
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/api/pixel.json输入
{
"type": "object",
"properties": {},
"required": []
}
响应数据
{
"type": "object"
}
文档
GET
/docs/api.json
列出所有 API 操作和 MCP 工具
docs_api
权限： public
示例
curl https://privatusanalytics.com/docs/api.json输入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": []
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"tool_name": {
"type": "string",
"description": "MCP 工具名称和 OpenAPI operationId"
},
"summary": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group": {
"type": "string"
},
"verb": {
"type": "string",
"description": "HTTP 方法"
},
"path": {
"type": "string",
"description": "路径模板。添加 .json 获取 JSON"
},
"permission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"input_schema": {
"type": "object",
"description": "输入的 JSON Schema"
},
"response_schema": {
"type": "object",
"description": "`data` 的 JSON Schema"
}
}
}
}
GET
/docs.json
列出文档页面
docs_list
权限： public
示例
curl https://privatusanalytics.com/docs.json输入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": []
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "页面标题"
},
"description": {
"type": "string",
"description": "一句话摘要"
},
"path": {
"type": "string",
"description": "页面路径。添加 .md 获取 Markdown，添加 .json 获取 JSON"
},
"section": {
"type": "string",
"description": "章节标识，例如 tracker"
}
}
}
}
GET
/openapi.json
整个 API 的 OpenAPI 3.1 文档
docs_openapi
权限： public
示例
curl https://privatusanalytics.com/openapi.json输入
{
"type": "object",
"properties": {},
"required": []
}
响应数据
{
"type": "object"
}
GET
/docs/search.json
搜索文档
docs_search
权限： public
示例
curl https://privatusanalytics.com/docs/search.json输入
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "搜索文本。留空则返回所有页面。",
"examples": [
"content security policy"
]
},
"limit": {
"type": "integer",
"description": "最大结果数（默认：有 q 时为 20，无 q 时为全部）"
}
},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "页面标题"
},
"path": {
"type": "string",
"description": "页面路径"
},
"section": {
"type": "string",
"description": "章节标题"
},
"headings": {
"type": "array",
"items": {
"type": "object"
},
"description": "页面上的标题：{ id, text }"
},
"excerpt": {
"type": "string",
"description": "描述或开头几句"
},
"score": {
"anyOf": [
{
"type": "integer",
"description": "相关度（仅在使用 q 搜索时）"
},
{
"type": "null"
}
]
}
}
}
GET
/docs/:section/:page.json
阅读文档页面（Markdown 和 HTML）
docs_get
section 和 page 来自页面路径 /docs/<section>/<page>。使用页面 "index" 获取章节概览。
权限： public
示例
curl https://privatusanalytics.com/docs/:section/:page.json输入
{
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "资源的 Section"
},
"page": {
"type": "string",
"description": "资源的 Page"
}
},
"required": [
"section",
"page"
]
}
响应数据
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "页面标题"
},
"description": {
"type": "string",
"description": "一句话摘要"
},
"path": {
"type": "string",
"description": "页面路径。添加 .md 获取 Markdown，添加 .json 获取 JSON"
},
"section": {
"type": "string",
"description": "章节标识，例如 tracker"
},
"headings": {
"type": "array",
"items": {
"type": "object"
},
"description": "页面上的章节（id 和文本）"
},
"full_markdown": {
"type": "string",
"description": "Markdown 格式的页面（含标题）"
},
"html": {
"type": "string",
"description": "渲染为 HTML 的页面正文"
}
}
}
正常运行时间
POST
/sites/:site_id/uptime.json
为站点添加正常运行时间检查
uptime_checks_create
权限： uptime.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "显示名称（默认为目标）"
},
"kind": {
"type": "string",
"description": "http（状态码）、keyword（正文包含）、tcp（host:port）或 dns（名称可解析）",
"enum": [
"http",
"keyword",
"tcp",
"dns"
],
"default": "http"
},
"url": {
"type": "string",
"description": "http/keyword 检查的 URL",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "tcp/dns 检查的主机名"
},
"port": {
"type": "integer",
"description": "tcp 检查的 TCP 端口"
},
"keyword": {
"type": "string",
"description": "响应正文必须包含的文本（keyword）"
},
"expected_status": {
"type": "integer",
"description": "期望的 HTTP 状态码",
"default": 200
},
"http_method": {
"type": "string",
"description": "HTTP 方法",
"enum": [
"GET",
"HEAD"
],
"default": "GET"
},
"interval_seconds": {
"type": "integer",
"description": "两次检查之间的秒数（适用套餐最小值，默认 300 或最小值）"
},
"timeout_seconds": {
"type": "integer",
"description": "探测超时前的秒数（1-30）",
"default": 20
},
"public": {
"type": "boolean",
"description": "可显示在公开状态页上",
"default": false
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/uptime/checks/:id.json
删除正常运行时间检查及其历史
uptime_checks_delete
权限： uptime.manage
示例
curl -X DELETE https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/uptime.json
列出站点的正常运行时间检查
uptime_checks_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅显示处于此状态的检查",
"enum": [
"up",
"down",
"pending",
"paused"
]
},
"query": {
"type": "string",
"description": "按名称或目标筛选"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/uptime/checks/:id/pause.json
暂停正常运行时间检查
uptime_checks_pause
权限： uptime.manage
示例
curl -X POST https://privatusanalytics.com/uptime/checks/:id/pause.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/uptime/checks/:id/resume.json
恢复已暂停的正常运行时间检查
uptime_checks_resume
权限： uptime.manage
示例
curl -X POST https://privatusanalytics.com/uptime/checks/:id/resume.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/uptime/checks/:id.json
获取正常运行时间检查：24 小时/7 天/30 天的正常运行时间、响应时间和事故
uptime_checks_get
权限： analytics.read
示例
curl https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"range": {
"type": "string",
"description": "响应时间图表的时间窗口",
"enum": [
"24h",
"7d",
"30d"
],
"default": "24h"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"check": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"uptime": {
"type": "object",
"description": "24 小时、7 天和 30 天的正常运行时间百分比"
},
"range": {
"type": "string",
"description": "response_times 的时间窗口"
},
"response_times": {
"type": "object",
"description": "每个时间段的平均响应毫秒数：{unit, labels, series: {location: [ms…]}}"
},
"incidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"started_at": {
"type": "string",
"format": "date-time"
},
"resolved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"duration_seconds": {
"type": "integer",
"description": "截至目前（如果仍未解决）"
},
"cause": {
"anyOf": [
{
"type": "string",
"description": "最常见的错误，例如 timeout 或 status_503"
},
{
"type": "null"
}
]
},
"failed_locations": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
PATCH
/uptime/checks/:id.json
更改正常运行时间检查
uptime_checks_update
权限： uptime.manage
示例
curl -X PATCH https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "显示名称（默认为目标）"
},
"kind": {
"type": "string",
"description": "http（状态码）、keyword（正文包含）、tcp（host:port）或 dns（名称可解析）",
"enum": [
"http",
"keyword",
"tcp",
"dns"
]
},
"url": {
"type": "string",
"description": "http/keyword 检查的 URL",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "tcp/dns 检查的主机名"
},
"port": {
"type": "integer",
"description": "tcp 检查的 TCP 端口"
},
"keyword": {
"type": "string",
"description": "响应正文必须包含的文本（keyword）"
},
"expected_status": {
"type": "integer",
"description": "期望的 HTTP 状态码"
},
"http_method": {
"type": "string",
"description": "HTTP 方法",
"enum": [
"GET",
"HEAD"
]
},
"interval_seconds": {
"type": "integer",
"description": "两次检查之间的秒数（适用套餐最小值，默认 300 或最小值）"
},
"timeout_seconds": {
"type": "integer",
"description": "探测超时前的秒数（1-30）"
},
"public": {
"type": "boolean",
"description": "可显示在公开状态页上"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/uptime/probes.json
探测数据中心、User-Agent 和出口 IP 范围（用于将我们的正常运行时间探测加入白名单）
uptime_probes_list
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/uptime/probes.json输入
{
"type": "object",
"properties": {},
"required": []
}
响应数据
{
"type": "object"
}
POST
/uptime/probes/results.json
提交来自外部探测代理的结果（Bearer 正常运行时间探测令牌）
uptime_probes_results
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/uptime/probes/results.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"check_id": {
"type": "string"
},
"location": {
"type": "string"
},
"ok": {
"type": "boolean"
},
"status_code": {
"type": "integer"
},
"response_ms": {
"type": "integer"
},
"error": {
"type": "string"
},
"checked_at": {
"type": "string",
"format": "date-time"
}
}
},
"description": "探测结果：[{check_id, location, ok, status_code, response_ms, error, checked_at}]"
}
},
"required": [
"results"
]
}
响应数据
{
"type": "object"
}
POST
/workspaces/:workspace_id/uptime.json
添加工作区正常运行时间检查（不绑定站点）
workspace_uptime_checks_create
权限： uptime.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "显示名称（默认为目标）"
},
"kind": {
"type": "string",
"description": "http（状态码）、keyword（正文包含）、tcp（host:port）或 dns（名称可解析）",
"enum": [
"http",
"keyword",
"tcp",
"dns"
],
"default": "http"
},
"url": {
"type": "string",
"description": "http/keyword 检查的 URL",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "tcp/dns 检查的主机名"
},
"port": {
"type": "integer",
"description": "tcp 检查的 TCP 端口"
},
"keyword": {
"type": "string",
"description": "响应正文必须包含的文本（keyword）"
},
"expected_status": {
"type": "integer",
"description": "期望的 HTTP 状态码",
"default": 200
},
"http_method": {
"type": "string",
"description": "HTTP 方法",
"enum": [
"GET",
"HEAD"
],
"default": "GET"
},
"interval_seconds": {
"type": "integer",
"description": "两次检查之间的秒数（适用套餐最小值，默认 300 或最小值）"
},
"timeout_seconds": {
"type": "integer",
"description": "探测超时前的秒数（1-30）",
"default": 20
},
"public": {
"type": "boolean",
"description": "可显示在公开状态页上",
"default": false
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/uptime.json
列出工作区中的所有正常运行时间检查
workspace_uptime_checks_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅显示处于此状态的检查",
"enum": [
"up",
"down",
"pending",
"paused"
]
},
"query": {
"type": "string",
"description": "按名称或目标筛选"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "检查 ID（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "该检查所属的站点"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可显示在状态页上"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
流量规则
POST
/sites/:site_id/traffic_rules.json
添加流量规则
traffic_rules_create
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events",
"enum": [
"hostnames",
"paths",
"referrers",
"countries",
"ip_ranges",
"user_agents",
"events"
]
},
"pattern": {
"type": "string",
"description": "要匹配的值。* 为通配符。ip_ranges 接受 IP 或 CIDR（v4/v6），countries 接受 ISO 代码",
"examples": [
"/admin/*"
]
},
"label": {
"type": "string",
"description": "可选备注，例如 \"Office\""
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"list",
"pattern",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 通配符，ip_ranges 使用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其列表的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/traffic_rules/:id.json
删除流量规则
traffic_rules_delete
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/traffic_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 通配符，ip_ranges 使用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其列表的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/traffic_rules.json
列出流量规则
traffic_rules_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"list": {
"type": "string",
"description": "仅显示此列表中的规则",
"enum": [
"hostnames",
"paths",
"referrers",
"countries",
"ip_ranges",
"user_agents",
"events"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 通配符，ip_ranges 使用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其列表的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/traffic_rules/test.json
测试某次请求在站点当前规则下是否会被计入
traffic_rules_test
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/traffic_rules/test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "页面 URL，例如 https://example.com/a"
},
"referrer": {
"type": "string",
"description": "来源 URL 或主机名"
},
"country": {
"type": "string",
"description": "ISO 国家/地区代码，例如 US"
},
"ip": {
"type": "string",
"description": "用于对照 ip_ranges 测试的 IP 地址（不会存储）"
},
"user_agent": {
"type": "string",
"description": "User-Agent 字符串（与采集时一样，简化为浏览器和主版本）"
},
"event": {
"type": "string",
"description": "自定义事件名称"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
PATCH
/sites/:site_id/traffic_rules/:id.json
更改流量规则
traffic_rules_update
权限： sites.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/traffic_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "新的模式"
},
"label": {
"type": "string",
"description": "新的标签"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 通配符，ip_ranges 使用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其列表的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
渠道规则
POST
/sites/:site_id/channel_rules.json
添加渠道规则
channel_rules_create
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/channel_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "要分配的渠道名称，例如 Partners"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "必须全部匹配的条件：[{\"field\": \"utm_source\", \"operator\": \"is\", \"value\": \"newsletter\"}]。字段：referrer_host、utm_source、utm_medium、utm_campaign、ref、path。运算符：is、contains、starts_with、regex。"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"channel",
"conditions",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"channel": {
"type": "string",
"description": "所有条件匹配时分配的渠道"
},
"position": {
"type": "integer",
"description": "评估顺序（先匹配者生效）"
},
"conditions": {
"type": "array",
"description": "条件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/channel_rules/:id.json
删除渠道规则
channel_rules_delete
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/channel_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"channel": {
"type": "string",
"description": "所有条件匹配时分配的渠道"
},
"position": {
"type": "integer",
"description": "评估顺序（先匹配者生效）"
},
"conditions": {
"type": "array",
"description": "条件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/channel_rules.json
按顺序列出渠道规则
channel_rules_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/channel_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"channel": {
"type": "string",
"description": "所有条件匹配时分配的渠道"
},
"position": {
"type": "integer",
"description": "评估顺序（先匹配者生效）"
},
"conditions": {
"type": "array",
"description": "条件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/channel_rules/:id/move.json
上移或下移渠道规则
channel_rules_move
权限： sites.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/channel_rules/:id/move.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"description": "规则要移动的方向",
"enum": [
"up",
"down",
"top",
"bottom"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"direction",
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"channel": {
"type": "string",
"description": "所有条件匹配时分配的渠道"
},
"position": {
"type": "integer",
"description": "评估顺序（先匹配者生效）"
},
"conditions": {
"type": "array",
"description": "条件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/channel_rules/preview.json
预览示例来源和 UTM 标记对应的渠道
channel_rules_preview
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/channel_rules/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"referrer": {
"type": "string",
"description": "来源 URL 或主机名"
},
"utm_source": {
"type": "string",
"description": "utm_source 值"
},
"utm_medium": {
"type": "string",
"description": "utm_medium 值"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"ref": {
"type": "string",
"description": "ref / via / source 参数"
},
"path": {
"type": "string",
"description": "落地页路径，例如 /pricing"
},
"paid_click": {
"type": "boolean",
"description": "URL 带有点击 ID，例如 gclid",
"default": false
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
PATCH
/sites/:site_id/channel_rules/:id.json
更改渠道规则
channel_rules_update
权限： sites.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/channel_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "要分配的渠道名称"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "必须全部匹配的条件：[{\"field\": \"utm_source\", \"operator\": \"is\", \"value\": \"newsletter\"}]。字段：referrer_host、utm_source、utm_medium、utm_campaign、ref、path。运算符：is、contains、starts_with、regex。"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "规则 ID"
},
"channel": {
"type": "string",
"description": "所有条件匹配时分配的渠道"
},
"position": {
"type": "integer",
"description": "评估顺序（先匹配者生效）"
},
"conditions": {
"type": "array",
"description": "条件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
漏斗
POST
/sites/:site_id/funnels.json
创建漏斗
funnels_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/funnels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "漏斗名称",
"examples": [
"Signup flow"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "有序步骤（2 到您的套餐上限）：[{\"type\": \"page|event|goal\", \"value\": \"/pricing | Signup | goal_…\", \"match\": \"exact|prefix|glob|regex\"（页面步骤）, \"name\": \"optional label\"}]"
},
"order_mode": {
"type": "string",
"description": "strict：按此顺序的步骤，any：任意顺序",
"enum": [
"strict",
"any"
],
"default": "strict"
},
"window": {
"type": "string",
"description": "转化窗口：visit，或 day（在一次访问内计量，访问不会跨越 UTC 日）",
"enum": [
"visit",
"day"
],
"default": "visit"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"steps",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 ID，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步骤：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到达第 1 步的访问数"
},
"completed": {
"type": "integer",
"description": "到达最后一步的访问数"
},
"conversion_rate": {
"type": "number",
"description": "完成数 ÷ 进入数，%"
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/funnels/:id.json
删除漏斗
funnels_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 ID，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步骤：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到达第 1 步的访问数"
},
"completed": {
"type": "integer",
"description": "到达最后一步的访问数"
},
"conversion_rate": {
"type": "number",
"description": "完成数 ÷ 进入数，%"
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/funnels.json
列出漏斗，含进入数、完成数和转化率
funnels_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/funnels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"page": {
"type": "integer",
"description": "页码",
"default": 1
},
"per_page": {
"type": "integer",
"description": "每页漏斗数（最多 100）",
"default": 25
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 ID，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步骤：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到达第 1 步的访问数"
},
"completed": {
"type": "integer",
"description": "到达最后一步的访问数"
},
"conversion_rate": {
"type": "number",
"description": "完成数 ÷ 进入数，%"
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/funnels/:id.json
漏斗报告：各步骤数量、转化、流失、步骤间耗时以及访问改去了哪里
funnels_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"breakdown": {
"type": "string",
"description": "按访问维度拆分各步骤数量",
"enum": [
"channel",
"device",
"country",
"utm_campaign",
"utm_source",
"browser",
"os"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "周期的 from/to（UTC）"
},
"funnel": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 ID，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步骤：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到达第 1 步的访问数"
},
"completed": {
"type": "integer",
"description": "到达最后一步的访问数"
},
"conversion_rate": {
"type": "number",
"description": "完成数 ÷ 进入数，%"
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"description": "漏斗定义"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day（day 在一次访问内计量）"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "每个步骤：index、name、type、value、count、step_conversion_rate、overall_conversion_rate、dropoff、dropoff_rate、median_seconds_from_previous、next_pages [{value, count}]"
},
"overall_conversion_rate": {
"type": "number",
"description": "最后一步 ÷ 第一步，%"
},
"breakdown": {
"anyOf": [
{
"type": "object",
"description": "dimension、label 和 rows [{value, counts, overall_conversion_rate}]"
},
{
"type": "null"
}
]
},
"comparison": {
"anyOf": [
{
"type": "object",
"description": "period、每个步骤的 counts、overall_conversion_rate 和 change（%）"
},
{
"type": "null"
}
]
}
}
}
PATCH
/sites/:site_id/funnels/:id.json
更新漏斗
funnels_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "漏斗名称",
"examples": [
"Signup flow"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "有序步骤（2 到您的套餐上限）：[{\"type\": \"page|event|goal\", \"value\": \"/pricing | Signup | goal_…\", \"match\": \"exact|prefix|glob|regex\"（页面步骤）, \"name\": \"optional label\"}]"
},
"order_mode": {
"type": "string",
"description": "strict：按此顺序的步骤，any：任意顺序",
"enum": [
"strict",
"any"
]
},
"window": {
"type": "string",
"description": "转化窗口：visit，或 day（在一次访问内计量，访问不会跨越 UTC 日）",
"enum": [
"visit",
"day"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 ID，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步骤：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到达第 1 步的访问数"
},
"completed": {
"type": "integer",
"description": "到达最后一步的访问数"
},
"conversion_rate": {
"type": "number",
"description": "完成数 ÷ 进入数，%"
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
爬虫
POST
/sites/:site_id/crawlers/connection.json
从 Cloudflare 区域同步 AI 爬虫访问（需要来自浏览器的 Cloudflare 授权）
crawlers_cloudflare_connect
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/crawlers/connection.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 区域 ID，来自 crawlers_cloudflare_zones",
"examples": [
"023e105f4ecef8ad9ca31a8372d0c353"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"zone_id",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 区域 ID"
},
"zone_name": {
"type": "string",
"description": "Cloudflare 区域名称，例如 example.com"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次导入爬虫访问记录的时间，首次导入之前为 null"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/crawlers/connection.json
断开 Cloudflare 并删除其导入的爬虫访问记录
crawlers_cloudflare_disconnect
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/crawlers/connection.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 区域 ID"
},
"zone_name": {
"type": "string",
"description": "Cloudflare 区域名称，例如 example.com"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次导入爬虫访问记录的时间，首次导入之前为 null"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/crawlers/sync.json
立即从 Cloudflare 导入爬虫访问记录
crawlers_cloudflare_sync
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/crawlers/sync.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 区域 ID"
},
"zone_name": {
"type": "string",
"description": "Cloudflare 区域名称，例如 example.com"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次导入爬虫访问记录的时间，首次导入之前为 null"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/crawlers/zones.json
列出您可以连接的 Cloudflare 区域（需要来自浏览器的 Cloudflare 授权）
crawlers_cloudflare_zones
权限： sites.manage
示例
curl https://privatusanalytics.com/sites/:site_id/crawlers/zones.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/crawlers.json
AI 爬虫报告：各爬虫随时间的请求数、每个爬虫的热门路径、按类别划分
crawlers_report
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/crawlers.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"category": {
"type": "string",
"description": "ai、search、seo、other 或 all",
"enum": [
"all",
"ai",
"search",
"seo",
"other"
],
"default": "ai"
},
"crawler": {
"type": "string",
"description": "仅显示此爬虫，例如 GPTBot"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
状态页
GET
/status/:slug/confirm/:token.json
通过邮件中的链接确认订阅
public_status_pages_confirm
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/status/:slug/confirm/:token.json输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
},
"slug": {
"type": "string",
"description": "资源的 Slug"
}
},
"required": [
"token",
"slug"
]
}
响应数据
{
"type": "object"
}
GET
/status/:slug.json
公开状态页：当前状态、90 天正常运行时间条、事故和公告
public_status_pages_get
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl https://privatusanalytics.com/status/:slug.json输入
{
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "资源的 Slug"
}
},
"required": [
"slug"
]
}
响应数据
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "operational、degraded 或 outage"
},
"checks": {
"type": "array",
"description": "每项：{name, status, uptime_90d, days: [{date, uptime, downtime_seconds}]}"
},
"posts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "公告 ID（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"incidents": {
"type": "array",
"description": "近期事故：{check, started_at, resolved_at, duration_seconds}"
}
}
}
POST
/status/:slug/subscribers.json
订阅邮箱地址（双重确认）
public_status_pages_subscribe
浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/status/:slug/subscribers.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "接收通知的邮箱地址",
"examples": [
"[email protected]"
]
},
"slug": {
"type": "string",
"description": "资源的 Slug"
}
},
"required": [
"email",
"slug"
]
}
响应数据
{
"type": "object"
}
POST
/status/:slug/unsubscribe/:token.json
使用邮件中的令牌退订
public_status_pages_unsubscribe
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/status/:slug/unsubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
},
"slug": {
"type": "string",
"description": "资源的 Slug"
}
},
"required": [
"token",
"slug"
]
}
响应数据
{
"type": "object"
}
POST
/status_pages/:status_page_id/posts.json
发布事故更新（会向订阅者发送邮件）
status_page_posts_create
权限： uptime.manage
示例
curl -X POST https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "标题，例如 \"Elevated error rates\""
},
"body": {
"type": "string",
"description": "更新文本（纯文本）"
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"default": "investigating"
},
"posted_at": {
"type": "string",
"format": "date-time",
"description": "发生时间（默认为现在）"
},
"notify": {
"type": "boolean",
"description": "向已确认的订阅者发送邮件",
"default": true
},
"status_page_id": {
"type": "string",
"description": "资源的 Status page"
}
},
"required": [
"title",
"status_page_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "公告 ID（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:status_page_id/posts/:id.json
删除状态页公告
status_page_posts_delete
权限： uptime.manage
示例
curl -X DELETE https://privatusanalytics.com/status_pages/:status_page_id/posts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"status_page_id": {
"type": "string",
"description": "资源的 Status page"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"status_page_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "公告 ID（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/status_pages/:status_page_id/posts.json
列出状态页上的公告
status_page_posts_list
权限： analytics.read
示例
curl https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅显示此状态的公告",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"status_page_id": {
"type": "string",
"description": "资源的 Status page"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"status_page_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "公告 ID（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/status_pages/:status_page_id/posts/:id.json
编辑状态页公告
status_page_posts_update
权限： uptime.manage
示例
curl -X PATCH https://privatusanalytics.com/status_pages/:status_page_id/posts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "标题"
},
"body": {
"type": "string",
"description": "更新文本（纯文本）"
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"notify": {
"type": "boolean",
"description": "如果状态变化，向已确认的订阅者发送邮件",
"default": true
},
"status_page_id": {
"type": "string",
"description": "资源的 Status page"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"status_page_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "公告 ID（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:status_page_id/subscribers/:id.json
移除订阅者
status_page_subscribers_delete
权限： uptime.manage
示例
curl -X DELETE https://privatusanalytics.com/status_pages/:status_page_id/subscribers/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"status_page_id": {
"type": "string",
"description": "资源的 Status page"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"status_page_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/status_pages/:status_page_id/subscribers.json
列出状态页的订阅者
status_page_subscribers_list
权限： uptime.manage
示例
curl https://privatusanalytics.com/status_pages/:status_page_id/subscribers.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"confirmed": {
"type": "boolean",
"description": "true：仅已确认，false：仅待确认"
},
"status_page_id": {
"type": "string",
"description": "资源的 Status page"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"status_page_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/status_pages.json
创建状态页
status_pages_create
权限： uptime.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "页面标题，例如 \"Acme status\""
},
"slug": {
"type": "string",
"description": "公开 URL 标识：/status/<slug>（默认取自名称）"
},
"description": {
"type": "string",
"description": "标题下方的介绍文字"
},
"logo_url": {
"type": "string",
"description": "徽标图片的 HTTPS URL"
},
"brand_color": {
"type": "string",
"description": "强调色，例如 #06755b"
},
"custom_domain": {
"type": "string",
"description": "自定义域名（CNAME 指向我们的主机），例如 status.example.com。留空则移除"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要显示的正常运行时间检查 ID（upc_…）"
},
"published": {
"type": "boolean",
"description": "对公众可见",
"default": true
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "状态页 ID（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公开 URL：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "显示的正常运行时间检查 ID"
},
"subscribers": {
"type": "integer",
"description": "已确认的订阅者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:id.json
删除状态页
status_pages_delete
权限： uptime.manage
示例
curl -X DELETE https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "状态页 ID（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公开 URL：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "显示的正常运行时间检查 ID"
},
"subscribers": {
"type": "integer",
"description": "已确认的订阅者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/status_pages.json
列出状态页
status_pages_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "按名称或标识筛选"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "状态页 ID（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公开 URL：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "显示的正常运行时间检查 ID"
},
"subscribers": {
"type": "integer",
"description": "已确认的订阅者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/status_pages/:id.json
获取状态页
status_pages_get
权限： analytics.read
示例
curl https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "状态页 ID（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公开 URL：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "显示的正常运行时间检查 ID"
},
"subscribers": {
"type": "integer",
"description": "已确认的订阅者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/status_pages/:id.json
更改状态页
status_pages_update
权限： uptime.manage
示例
curl -X PATCH https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "页面标题，例如 \"Acme status\""
},
"slug": {
"type": "string",
"description": "公开 URL 标识：/status/<slug>（默认取自名称）"
},
"description": {
"type": "string",
"description": "标题下方的介绍文字"
},
"logo_url": {
"type": "string",
"description": "徽标图片的 HTTPS URL"
},
"brand_color": {
"type": "string",
"description": "强调色，例如 #06755b"
},
"custom_domain": {
"type": "string",
"description": "自定义域名（CNAME 指向我们的主机），例如 status.example.com。留空则移除"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要显示的正常运行时间检查 ID（upc_…）"
},
"published": {
"type": "boolean",
"description": "对公众可见"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "状态页 ID（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公开 URL：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "显示的正常运行时间检查 ID"
},
"subscribers": {
"type": "integer",
"description": "已确认的订阅者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
目标
POST
/sites/:site_id/goals/:id/archive.json
归档目标（在报告中隐藏）
goals_archive
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/archive.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/goals.json
创建目标
goals_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/goals.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "目标名称",
"examples": [
"Signed up"
]
},
"kind": {
"type": "string",
"description": "page（访问页面）、event（自定义事件）、engagement（滚动或页面停留时间）、outbound（外部链接点击）或 download（文件下载）",
"enum": [
"page",
"event",
"engagement",
"outbound",
"download"
]
},
"match_type": {
"type": "string",
"description": "pattern 如何匹配路径（page、engagement）、链接域名（outbound）或文件（download）：exact、prefix、glob (*) 或 regex",
"enum": [
"exact",
"prefix",
"glob",
"regex"
],
"default": "exact"
},
"pattern": {
"type": "string",
"description": "路径、域名或文件模式，例如 /pricing、/blog/*、stripe.com 或 *.pdf"
},
"hostname": {
"type": "string",
"description": "仅统计此主机名上的页面（页面目标）"
},
"event_name": {
"type": "string",
"description": "自定义事件名称（事件目标）"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "事件属性条件：[{\"key\": \"plan\", \"operator\": \"is|is_not|contains|gt|lt\", \"value\": \"pro\"}]",
"default": []
},
"scroll_threshold": {
"type": "integer",
"description": "engagement：需要达到的滚动深度百分比"
},
"time_threshold_seconds": {
"type": "integer",
"description": "engagement：页面停留秒数"
},
"value_mode": {
"type": "string",
"description": "none、fixed（每次转化 fixed_value）或 revenue（事件收入）",
"enum": [
"none",
"fixed",
"revenue"
],
"default": "none"
},
"fixed_value": {
"type": "number",
"description": "每次转化的固定价值，使用站点货币，例如 50.0"
},
"count_mode": {
"type": "string",
"description": "价值按 once_per_visit 或每次完成计算",
"enum": [
"once_per_visit",
"every"
],
"default": "once_per_visit"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"kind",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/goals/:id.json
删除目标（数据会保留）
goals_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/goals/:id/duplicate.json
复制目标
goals_duplicate
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/duplicate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "副本的名称"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/goals.json
列出目标，含某个周期的完成数、转化数、转化率和价值
goals_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/goals.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"status": {
"type": "string",
"description": "active、archived 或 all 目标",
"enum": [
"active",
"archived",
"all"
],
"default": "active"
},
"page": {
"type": "integer",
"description": "页码",
"default": 1
},
"per_page": {
"type": "integer",
"description": "每页目标数（最多 100）",
"default": 25
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/goals/:id.json
目标报告：指标、图表、细分以及转化路径
goals_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"interval": {
"type": "string",
"description": "图表时间段大小",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "周期的 from/to（UTC）"
},
"goal": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"description": "目标定义"
},
"metrics": {
"type": "object",
"description": "completions、conversions、conversion_rate（%）、value（最小货币单位）"
},
"comparison_period": {
"anyOf": [
{
"type": "object",
"description": "对比的 from/to"
},
{
"type": "null"
}
]
},
"comparison": {
"anyOf": [
{
"type": "object",
"description": "对比周期的指标"
},
{
"type": "null"
}
]
},
"change": {
"anyOf": [
{
"type": "object",
"description": "相对对比的变化，每个指标的百分比"
},
{
"type": "null"
}
]
},
"interval": {
"type": "string",
"description": "图表时间段大小"
},
"series": {
"type": "array",
"items": {
"type": "object"
},
"description": "每个时间段：date、completions、conversions、conversion_rate"
},
"breakdowns": {
"type": "object",
"description": "按转化数排列的 channel、utm_campaign、entry_page、country 和 device 的热门值：value、completions、conversions、conversion_rate"
},
"journey": {
"anyOf": [
{
"type": "object",
"description": "converting_visits、median_seconds_to_convert、median_pages_before 和 pages_before（访问中此前浏览的页面，按转化访问数统计）"
},
{
"type": "null"
}
]
}
}
}
POST
/sites/:site_id/goals/:id/unarchive.json
恢复已归档的目标
goals_unarchive
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/unarchive.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/goals/:id.json
更新目标
goals_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "目标名称",
"examples": [
"Signed up"
]
},
"kind": {
"type": "string",
"description": "page（访问页面）、event（自定义事件）、engagement（滚动或页面停留时间）、outbound（外部链接点击）或 download（文件下载）",
"enum": [
"page",
"event",
"engagement",
"outbound",
"download"
]
},
"match_type": {
"type": "string",
"description": "pattern 如何匹配路径（page、engagement）、链接域名（outbound）或文件（download）：exact、prefix、glob (*) 或 regex",
"enum": [
"exact",
"prefix",
"glob",
"regex"
]
},
"pattern": {
"type": "string",
"description": "路径、域名或文件模式，例如 /pricing、/blog/*、stripe.com 或 *.pdf"
},
"hostname": {
"type": "string",
"description": "仅统计此主机名上的页面（页面目标）"
},
"event_name": {
"type": "string",
"description": "自定义事件名称（事件目标）"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "事件属性条件：[{\"key\": \"plan\", \"operator\": \"is|is_not|contains|gt|lt\", \"value\": \"pro\"}]"
},
"scroll_threshold": {
"type": "integer",
"description": "engagement：需要达到的滚动深度百分比"
},
"time_threshold_seconds": {
"type": "integer",
"description": "engagement：页面停留秒数"
},
"value_mode": {
"type": "string",
"description": "none、fixed（每次转化 fixed_value）或 revenue（事件收入）",
"enum": [
"none",
"fixed",
"revenue"
]
},
"fixed_value": {
"type": "number",
"description": "每次转化的固定价值，使用站点货币，例如 50.0"
},
"count_mode": {
"type": "string",
"description": "价值按 once_per_visit 或每次完成计算",
"enum": [
"once_per_visit",
"every"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目标 ID，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路径、域名或文件模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主机名限制（页面目标）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自定义事件名称（事件目标）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件属性条件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "engagement：滚动百分比"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "engagement：页面停留秒数"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小货币单位计的固定价值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "匹配的事件，含重复"
},
"conversions": {
"type": "integer",
"description": "至少完成一次的访问数"
},
"conversion_rate": {
"type": "number",
"description": "转化数 ÷ 访问数（或 ÷ 访客数，取决于站点设置），%"
},
"value": {
"type": "integer",
"description": "以站点货币最小单位计的目标价值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "转化数相对上一周期的变化，%"
},
{
"type": "null"
}
]
}
},
"description": "周期统计（仅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
站点
POST
/sites/:site_id/data_reset.json
删除某个日期范围内的所有事件和访问（在后台运行，无法撤销）
sites_reset_data
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/data_reset.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "要删除的第一天（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "要删除的最后一天，含当天"
},
"confirm": {
"type": "string",
"description": "输入域名以确认"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"from",
"to",
"confirm",
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/filter_stats.json
已过滤流量摘要：按原因和国家/地区统计机器人、流量规则或 PII 脱敏（仅计数）
sites_filter_stats
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/filter_stats.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "bot（已过滤的机器人）、rule（流量规则）或 redaction（PII 清除器）",
"enum": [
"bot",
"rule",
"redaction"
],
"default": "bot"
},
"days": {
"type": "integer",
"description": "回溯的天数（1-395）",
"default": 30
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/access.json
列出成员以及他们是否可以查看此站点
sites_access_list
权限： members.manage
示例
curl https://privatusanalytics.com/sites/:site_id/access.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"format": "uuid",
"description": "成员关系 ID"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"access": {
"type": "boolean",
"description": "可以查看此站点"
},
"locked": {
"type": "boolean",
"description": "所有者和管理员始终拥有访问权限"
}
}
}
PATCH
/sites/:site_id/access.json
授予或移除某位成员对此站点的访问权限
sites_access_update
权限： members.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/access.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"description": "来自 sites_access_list 的成员关系 ID"
},
"access": {
"type": "boolean",
"description": "true 表示授予访问权限，false 表示移除"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"membership_id",
"access",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"format": "uuid",
"description": "成员关系 ID"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"access": {
"type": "boolean",
"description": "可以查看此站点"
},
"locked": {
"type": "boolean",
"description": "所有者和管理员始终拥有访问权限"
}
}
}
POST
/sites/:site_id/favorite.json
为站点加星标（在全部站点中置顶）
sites_favorite
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/favorite.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/favorite.json
取消站点星标
sites_unfavorite
权限： analytics.read
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/favorite.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/setup.json
站点的安装状态和代码片段
sites_setup_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/setup.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
POST
/transfers/:token/accept.json
接受站点转移到您的某个工作区
site_transfers_accept
权限： public
示例
curl -X POST https://privatusanalytics.com/transfers/:token/accept.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "要将站点移入的工作区（ws_…）"
},
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"workspace_id",
"token"
]
}
响应数据
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在转移的站点"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "当前工作区名称"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收方工作区"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "接收方邮箱"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/transfer.json
开始将站点转移到另一个工作区（会向接收方发送邮件）
sites_transfer_start
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "将接收站点的人的邮箱（对方选择自己的某个工作区）"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"email",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在转移的站点"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "当前工作区名称"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收方工作区"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "接收方邮箱"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/transfer.json
取消待处理的站点转移
sites_transfer_cancel
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在转移的站点"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "当前工作区名称"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收方工作区"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "接收方邮箱"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/transfers/:token.json
通过邮件中的令牌获取待处理的转移
site_transfers_get
权限： public
示例
curl https://privatusanalytics.com/transfers/:token.json输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在转移的站点"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "当前工作区名称"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收方工作区"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "接收方邮箱"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/sites.json
添加站点
sites_create
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "主域名，例如 example.com",
"examples": [
"example.com"
]
},
"name": {
"type": "string",
"description": "显示名称（默认为域名）"
},
"timezone": {
"type": "string",
"description": "报告时区"
},
"currency": {
"type": "string",
"description": "收入货币（ISO 4217）"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"domain",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:id.json
删除站点（7 天后清除）
sites_delete
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"confirm": {
"type": "string",
"description": "输入域名以确认"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"confirm",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/sites.json
列出工作区中的站点
sites_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "按域名或名称筛选"
},
"label": {
"type": "string",
"description": "仅显示带此标签的站点"
},
"sort": {
"type": "string",
"description": "position（您的排序）、name，或过去 30 天的 visitors（从多到少）",
"enum": [
"position",
"name",
"visitors"
],
"default": "position"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:id.json
获取站点及其所有设置
sites_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:id.json
更新站点设置
sites_update
权限： sites.manage
示例
curl -X PATCH https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "显示名称"
},
"domain": {
"type": "string",
"description": "主域名"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "其他主机名"
},
"multi_domain_mode": {
"type": "string",
"description": "combined：跨域名视为同一访客",
"enum": [
"combined",
"separate"
]
},
"timezone": {
"type": "string",
"description": "报告时区"
},
"currency": {
"type": "string",
"description": "收入货币（ISO 4217）"
},
"week_start": {
"type": "integer",
"description": "0 = 星期日，1 = 星期一"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "用于站点分组的标签"
},
"honor_dnt": {
"type": "boolean",
"description": "跳过发送 DNT 的访客"
},
"honor_gpc": {
"type": "boolean",
"description": "跳过发送 GPC 的访客"
},
"pii_scrubber": {
"type": "boolean",
"description": "清除邮箱、令牌、ID"
},
"redaction_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"pattern": {
"type": "string"
}
}
},
"description": "自定义清除正则表达式"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "在路径上保留的查询参数"
},
"path_masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"replacement": {
"type": "string"
}
}
},
"description": "路径遮蔽规则，例如 /u/* -> /u/:id"
},
"retention_months": {
"type": "integer",
"description": "删除早于此时间的数据"
},
"bot_filtering": {
"type": "boolean",
"description": "过滤机器人流量"
},
"traffic_rule_modes": {
"type": "object",
"additionalProperties": true,
"description": "每个流量规则列表的 block 或 allow"
},
"vitals_sample_rate": {
"type": "integer",
"description": "网页性能指标采样百分比"
},
"conversion_denominator": {
"type": "string",
"description": "转化率按访问数或访客数计算",
"enum": [
"visits",
"visitors"
]
},
"public_dashboard": {
"type": "boolean",
"description": "任何拿到链接的人都可以查看统计"
},
"public_indexable": {
"type": "boolean",
"description": "允许搜索引擎索引公开页面"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
细分
POST
/sites/:site_id/segments.json
将筛选条件保存为细分
segments_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/segments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "细分名称，例如“来自广告的移动端访客”",
"examples": [
"Mobile visitors from ads"
]
},
"description": {
"type": "string",
"description": "可选的说明，描述此细分的用途（最多 300 个字符）",
"examples": [
"People who might buy the Pro plan"
]
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件，必须全部匹配。每一项是一个条件 [\"dimension\", \"operator\", \"value\"]，或在多个条件中任一匹配即可时使用 {\"any\": [conditions]}。维度：page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country（ISO 代码，例如 US）, language, device（desktop, mobile, tablet, tv, other）, browser, browser_version, os, os_version, screen, goal（目标 ID）, event（自定义事件名称）和 prop:<key>（自定义事件属性）。运算符：is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of 和 none_of（值为列表），gt 和 lt（数字），between（包含两个数字的列表）。也接受细分表单中的行：{\"dimension\", \"operator\", \"value\", \"property\"（用于维度 prop）, \"join\": \"and\" 或 \"or\"（or 会将该行与上一行组合）}。示例：[[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
]
},
"shared": {
"type": "boolean",
"description": "对所有有权访问该站点的人可见（false：仅您自己）",
"default": true
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"filters",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "细分 ID，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此细分的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "采用统计筛选格式的筛选条件：必须全部匹配的条件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 分组"
},
"summary": {
"type": "string",
"description": "用自然语言表述的筛选条件，例如“来自美国、使用移动设备并浏览过 /pricing 的访客”"
},
"shared": {
"type": "boolean",
"description": "对所有有权访问该站点的人可见"
},
"mine": {
"type": "boolean",
"description": "由您创建"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/segments/:id.json
删除细分
segments_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "细分 ID，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此细分的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "采用统计筛选格式的筛选条件：必须全部匹配的条件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 分组"
},
"summary": {
"type": "string",
"description": "用自然语言表述的筛选条件，例如“来自美国、使用移动设备并浏览过 /pricing 的访客”"
},
"shared": {
"type": "boolean",
"description": "对所有有权访问该站点的人可见"
},
"mine": {
"type": "boolean",
"description": "由您创建"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/segments.json
列出您可在站点上使用的细分
segments_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/segments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "细分 ID，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此细分的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "采用统计筛选格式的筛选条件：必须全部匹配的条件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 分组"
},
"summary": {
"type": "string",
"description": "用自然语言表述的筛选条件，例如“来自美国、使用移动设备并浏览过 /pricing 的访客”"
},
"shared": {
"type": "boolean",
"description": "对所有有权访问该站点的人可见"
},
"mine": {
"type": "boolean",
"description": "由您创建"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/sites/:site_id/segments/preview.json
用自然语言描述筛选条件，并统计过去 30 天内匹配的访客数
segments_preview
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/segments/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"filters": {
"type": "array",
"items": {},
"description": "筛选条件，必须全部匹配。每一项是一个条件 [\"dimension\", \"operator\", \"value\"]，或在多个条件中任一匹配即可时使用 {\"any\": [conditions]}。维度：page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country（ISO 代码，例如 US）, language, device（desktop, mobile, tablet, tv, other）, browser, browser_version, os, os_version, screen, goal（目标 ID）, event（自定义事件名称）和 prop:<key>（自定义事件属性）。运算符：is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of 和 none_of（值为列表），gt 和 lt（数字），between（包含两个数字的列表）。也接受细分表单中的行：{\"dimension\", \"operator\", \"value\", \"property\"（用于维度 prop）, \"join\": \"and\" 或 \"or\"（or 会将该行与上一行组合）}。示例：[[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
],
"default": []
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/segments/:id.json
获取细分
segments_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "细分 ID，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此细分的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "采用统计筛选格式的筛选条件：必须全部匹配的条件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 分组"
},
"summary": {
"type": "string",
"description": "用自然语言表述的筛选条件，例如“来自美国、使用移动设备并浏览过 /pricing 的访客”"
},
"shared": {
"type": "boolean",
"description": "对所有有权访问该站点的人可见"
},
"mine": {
"type": "boolean",
"description": "由您创建"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/segments/:id.json
重命名细分或更改其筛选条件或分享设置
segments_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "细分名称"
},
"description": {
"type": "string",
"description": "可选的说明，描述此细分的用途（最多 300 个字符，留空则清除）"
},
"filters": {
"type": "array",
"items": {},
"description": "用于替换的筛选条件，格式与创建时相同。筛选条件，必须全部匹配。每一项是一个条件 [\"dimension\", \"operator\", \"value\"]，或在多个条件中任一匹配即可时使用 {\"any\": [conditions]}。维度：page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country（ISO 代码，例如 US）, language, device（desktop, mobile, tablet, tv, other）, browser, browser_version, os, os_version, screen, goal（目标 ID）, event（自定义事件名称）和 prop:<key>（自定义事件属性）。运算符：is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of 和 none_of（值为列表），gt 和 lt（数字），between（包含两个数字的列表）。也接受细分表单中的行：{\"dimension\", \"operator\", \"value\", \"property\"（用于维度 prop）, \"join\": \"and\" 或 \"or\"（or 会将该行与上一行组合）}。示例：[[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
]
},
"shared": {
"type": "boolean",
"description": "对站点上的所有人可见"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "细分 ID，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此细分的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "采用统计筛选格式的筛选条件：必须全部匹配的条件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 分组"
},
"summary": {
"type": "string",
"description": "用自然语言表述的筛选条件，例如“来自美国、使用移动设备并浏览过 /pricing 的访客”"
},
"shared": {
"type": "boolean",
"description": "对所有有权访问该站点的人可见"
},
"mine": {
"type": "boolean",
"description": "由您创建"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
网站
GET
/changelog.json
列出更新日志条目
changelog_list
已发布的产品更新，最新的在前。也可通过 /changelog.rss 以 RSS 订阅。
权限： public
示例
curl https://privatusanalytics.com/changelog.json输入
{
"type": "object",
"properties": {
"area": {
"type": "string",
"description": "仅显示此产品领域的条目",
"enum": [
"product",
"dashboard",
"tracker",
"privacy",
"api",
"integrations",
"billing",
"docs"
]
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": []
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "条目 ID，例如 chg_7Q2K9XH3AB"
},
"title": {
"type": "string",
"description": "标题"
},
"area": {
"type": "string",
"description": "产品领域，例如 dashboard、tracker、api"
},
"body": {
"type": "string",
"description": "Markdown 正文"
},
"published_at": {
"type": "string",
"format": "date-time",
"description": "发布时间"
},
"url": {
"type": "string",
"description": "永久链接"
}
}
}
}
GET
/changelog/:id.json
获取更新日志条目
changelog_get
权限： public
示例
curl https://privatusanalytics.com/changelog/:id.json输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "条目 ID，例如 chg_7Q2K9XH3AB"
},
"title": {
"type": "string",
"description": "标题"
},
"area": {
"type": "string",
"description": "产品领域，例如 dashboard、tracker、api"
},
"body": {
"type": "string",
"description": "Markdown 正文"
},
"published_at": {
"type": "string",
"format": "date-time",
"description": "发布时间"
},
"url": {
"type": "string",
"description": "永久链接"
}
}
}
POST
/contact.json
向 Privatus Analytics 团队发送消息
contact_create
浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/contact.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "您的姓名",
"examples": [
"Ada Lovelace"
]
},
"email": {
"type": "string",
"description": "我们回复的邮箱",
"examples": [
"[email protected]"
]
},
"company": {
"type": "string",
"description": "公司或组织（可选）"
},
"topic": {
"type": "string",
"description": "消息的主题",
"enum": [
"general",
"sales",
"support",
"privacy",
"security",
"partnerships",
"press"
],
"default": "general"
},
"message": {
"type": "string",
"description": "您的消息（10 到 5,000 个字符）"
},
"website": {
"type": "string",
"description": "请留空。这是针对机器人的垃圾信息陷阱。填写了的提交会被丢弃"
}
},
"required": [
"name",
"email",
"message"
]
}
响应数据
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受时始终为 true"
},
"message": {
"type": "string",
"description": "接下来会发生什么"
}
}
}
POST
/newsletter/confirm.json
确认新闻通讯订阅（签名令牌）
newsletter_confirm
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/newsletter/confirm.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "确认邮件中的签名令牌"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受时始终为 true"
},
"message": {
"type": "string",
"description": "接下来会发生什么"
}
}
}
POST
/newsletter.json
为新闻通讯订阅一个邮箱
newsletter_subscribe
浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/newsletter.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "要订阅的邮箱地址。确认链接会发送到该邮箱",
"examples": [
"[email protected]"
]
},
"website": {
"type": "string",
"description": "请留空。这是针对机器人的垃圾信息陷阱。填写了的提交会被丢弃"
}
},
"required": [
"email"
]
}
响应数据
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受时始终为 true"
},
"message": {
"type": "string",
"description": "接下来会发生什么"
}
}
}
POST
/newsletter/unsubscribe.json
使用签名链接令牌退订
newsletter_unsubscribe
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/newsletter/unsubscribe.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "退订链接中的签名令牌"
},
"list": {
"type": "string",
"description": "newsletter（默认：链接对应的列表）或 marketing（所有营销邮件）",
"enum": [
"newsletter",
"marketing"
]
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受时始终为 true"
},
"message": {
"type": "string",
"description": "接下来会发生什么"
}
}
}
GET
/pricing.json
获取套餐、价格和套餐限额
pricing_get
与定价页面相同的数据：事件档位、各项套餐限额以及哪些计为事件。传入 events 可获取匹配的档位。
权限： public
示例
curl https://privatusanalytics.com/pricing.json输入
{
"type": "object",
"properties": {
"events": {
"type": "integer",
"description": "预计每月浏览量加自定义事件数。以 `recommendation` 返回匹配的档位",
"examples": [
750000
]
},
"interval": {
"type": "string",
"description": "所显示价格的计费周期：month，或 year（月价的 10 倍）",
"enum": [
"month",
"year"
],
"default": "month"
}
},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "所有价格的货币（USD）"
},
"tax_included": {
"type": "boolean",
"description": "始终为 true。价格已含增值税或销售税，所示价格即实付价格"
},
"interval": {
"type": "string",
"description": "month 或 year。价格对应此周期"
},
"annual_multiplier": {
"type": "integer",
"description": "年价 = 月价 x 此数值（免费两个月）"
},
"free_events": {
"type": "integer",
"description": "免费套餐每月包含的事件数"
},
"badge_bonus": {
"type": "integer",
"description": "展示可选徽章时每月额外免费的事件数"
},
"tiers": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件阶梯：该周期的 { events, pro, business } 价格（仅提供 Business 的档位 pro 为 null），以及月价"
},
"plans": {
"type": "array",
"items": {
"type": "object"
},
"description": "套餐，含 { id, name, from_price, limits }。限额为 null 表示无限制"
},
"counted": {
"type": "array",
"items": {
"type": "string"
},
"description": "哪些计为计费事件"
},
"not_counted": {
"type": "array",
"items": {
"type": "string"
},
"description": "哪些绝不计入用量"
},
"recommendation": {
"anyOf": [
{
"type": "object",
"description": "针对 `events` 输入的 { events, plan, tier_events, price }，未提供数量时为 null"
},
{
"type": "null"
}
]
}
}
}
GET
/status.json
获取当前系统状态
status_get
数据库、Redis 和后台作业的健康状况，最多每 15 秒检查一次。
权限： public
示例
curl https://privatusanalytics.com/status.json输入
{
"type": "object",
"properties": {
"fresh": {
"type": "boolean",
"description": "跳过 15 秒缓存并立即重新检查",
"default": false
}
},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "整体：operational、degraded 或 outage"
},
"checked_at": {
"type": "string",
"format": "date-time",
"description": "检查运行的时间（最多缓存 15 秒）"
},
"components": {
"type": "array",
"items": {
"type": "object"
},
"description": "每个组件：{ id, name, status, detail, latency_ms }，队列另有 queue_latency_s 和 queue_depth"
}
}
}
GET
/tools/consent-gap.json
估算基于同意的分析工具漏掉的流量
tools_consent_gap
权限： public
示例
curl https://privatusanalytics.com/tools/consent-gap.json输入
{
"type": "object",
"properties": {
"monthly_visitors": {
"type": "integer",
"description": "每月访客数（来自您的服务器日志或当前的分析工具）",
"examples": [
50000
]
},
"consent_rate": {
"type": "number",
"description": "在您的横幅中接受分析 Cookie 的访客百分比（0-100）",
"examples": [
55
]
},
"adblock_share": {
"type": "number",
"description": "其拦截器会阻止分析脚本的访客百分比（0-100）",
"default": 25.0
}
},
"required": [
"monthly_visitors",
"consent_rate"
]
}
响应数据
{
"type": "object",
"properties": {
"monthly_visitors": {
"type": "integer",
"description": "输入：每月访客数"
},
"consent_rate": {
"type": "number",
"description": "输入：接受分析 Cookie 的百分比"
},
"adblock_share": {
"type": "number",
"description": "输入：其拦截器会阻止脚本的百分比"
},
"measured_with_consent": {
"type": "integer",
"description": "基于同意的工具可以测量的访客"
},
"missed": {
"type": "integer",
"description": "它漏掉的访客"
},
"missed_percent": {
"type": "number",
"description": "漏掉的访客占比，百分比"
},
"measured_cookieless": {
"type": "integer",
"description": "在被拦截比例相同的情况下，没有横幅的无 Cookie 工具能够统计到的访客数"
},
"recovered_by_cookieless": {
"type": "integer",
"description": "无 Cookie 估算与基于同意的估算之间的差值"
}
}
}
GET
/tools/header-checker.json
检查页面的 Referrer-Policy 和 CSP 是否适合分析
tools_header_check
权限： public
示例
curl https://privatusanalytics.com/tools/header-checker.json输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要检查的公开页面（http 或 https）",
"examples": [
"https://example.com"
]
}
},
"required": [
"url"
]
}
响应数据
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "重定向后的最终 URL"
},
"status": {
"type": "integer",
"description": "最终响应的 HTTP 状态"
},
"findings": {
"type": "array",
"items": {
"type": "object"
},
"description": "检查项：{ check, value, level (ok, warn, info), note }"
}
}
}
GET
/tools/privacy-policy-generator.json
为 Privatus Analytics 起草一段隐私政策文字
tools_privacy_policy
权限： public
示例
curl https://privatusanalytics.com/tools/privacy-policy-generator.json输入
{
"type": "object",
"properties": {
"site_name": {
"type": "string",
"description": "您的网站或公司名称",
"examples": [
"Example Books"
]
},
"contact_email": {
"type": "string",
"description": "要提及的隐私联系人（可选）"
},
"honors_gpc": {
"type": "boolean",
"description": "是否遵循“请勿跟踪”和全局隐私控制（默认）",
"default": true
}
},
"required": [
"site_name"
]
}
响应数据
{
"type": "object",
"properties": {
"site_name": {
"type": "string",
"description": "输入：站点或公司名称"
},
"paragraphs": {
"type": "array",
"items": {
"type": "string"
},
"description": "政策文本，每项一个段落"
},
"text": {
"type": "string",
"description": "用空行连接的段落"
}
}
}
GET
/tools/qr-code.json
生成 SVG 二维码
tools_qr_code
权限： public
示例
curl https://privatusanalytics.com/tools/qr-code.json输入
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "要编码的 URL 或文本（最多 1,000 个字符）",
"examples": [
"https://example.com/?utm_source=poster"
]
},
"level": {
"type": "string",
"description": "纠错：l（7%）、m（15%）、q（25%）、h（30%）",
"enum": [
"l",
"m",
"q",
"h"
],
"default": "m"
}
},
"required": [
"text"
]
}
响应数据
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "已编码的文本"
},
"level": {
"type": "string",
"description": "纠错级别"
},
"size": {
"type": "integer",
"description": "每边的模块数"
},
"svg": {
"type": "string",
"description": "独立的 SVG 文档"
}
}
}
GET
/tools/tracker-scanner.json
列出页面上的 Cookie 和已知跟踪器
tools_tracker_scan
权限： public
示例
curl https://privatusanalytics.com/tools/tracker-scanner.json输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要扫描的公开页面（http 或 https）",
"examples": [
"https://example.com"
]
}
},
"required": [
"url"
]
}
响应数据
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "重定向后的最终 URL"
},
"status": {
"type": "integer",
"description": "最终响应的 HTTP 状态"
},
"truncated": {
"type": "boolean",
"description": "页面超过 1 MB 且只扫描了前 1 MB 时为 True"
},
"cookies": {
"type": "array",
"items": {
"type": "object"
},
"description": "HTTP 响应设置的 Cookie：{ name, domain, path, expires, secure, http_only, same_site }。绝不返回值"
},
"trackers": {
"type": "array",
"items": {
"type": "object"
},
"description": "页面引用的已知工具：{ name, category, match, evidence }"
},
"third_party_hosts": {
"type": "array",
"items": {
"type": "string"
},
"description": "页面从中加载资源的其他域名"
}
}
}
GET
/tools/utm-builder.json
生成带 UTM 参数的营销活动 URL
tools_utm_builder
权限： public
示例
curl https://privatusanalytics.com/tools/utm-builder.json输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "落地页 URL",
"examples": [
"https://example.com/pricing"
]
},
"source": {
"type": "string",
"description": "utm_source：流量来自哪里",
"examples": [
"newsletter"
]
},
"medium": {
"type": "string",
"description": "utm_medium：渠道，例如 email、cpc、social",
"examples": [
"email"
]
},
"campaign": {
"type": "string",
"description": "utm_campaign：营销活动名称",
"examples": [
"fall_launch"
]
},
"term": {
"type": "string",
"description": "utm_term：付费搜索关键词（可选）"
},
"content": {
"type": "string",
"description": "utm_content：哪个链接或创意（可选）"
}
},
"required": [
"url",
"source",
"medium",
"campaign"
]
}
响应数据
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "带有 UTM 参数的落地页 URL"
},
"params": {
"type": "object",
"description": "已添加的 UTM 参数"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "值得修复的问题（大小写、空格、个人数据）"
}
}
}
POST
/waitlist.json
加入候补名单（欧盟托管）
waitlist_join
浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/waitlist.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "接收通知的邮箱",
"examples": [
"[email protected]"
]
},
"list": {
"type": "string",
"description": "要加入哪个候补名单",
"enum": [
"eu_hosting"
],
"default": "eu_hosting"
},
"website": {
"type": "string",
"description": "请留空。这是针对机器人的垃圾信息陷阱。填写了的提交会被丢弃"
}
},
"required": [
"email"
]
}
响应数据
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受时始终为 true"
},
"message": {
"type": "string",
"description": "接下来会发生什么"
}
}
}
联盟计划
GET
/account/affiliate/commissions.json
列出您的联盟佣金
affiliate_commissions_list
佣金、因退款和拒付产生的追回以及冲正，最新的在前。金额以分为单位。
权限： member
示例
curl https://privatusanalytics.com/account/affiliate/commissions.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅返回此状态的佣金",
"enum": [
"pending",
"approved",
"paid",
"void"
]
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": []
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "佣金 ID"
},
"kind": {
"type": "string",
"description": "commission、clawback（退款或拒付）或 reversal"
},
"status": {
"type": "string",
"description": "pending（保留中）、approved（可支付）、paid 或 void"
},
"amount_cents": {
"type": "integer",
"description": "您的分成，以分为单位（追回时为负数）"
},
"basis_cents": {
"type": "integer",
"description": "计算所依据的净付款额（不含税），以分为单位"
},
"currency": {
"type": "string",
"description": "ISO 货币代码"
},
"earned_at": {
"type": "string",
"format": "date-time",
"description": "付款（或退款）发生的时间"
},
"approved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "变为可支付的时间"
},
{
"type": "null"
}
]
},
"paid_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "支付时间"
},
{
"type": "null"
}
]
}
}
}
}
GET
/account/affiliate/signup-box.json
获取您的联盟注册框代码和结果
affiliate_signup_box_get
所选主题下注册框的嵌入代码（脚本和纯 iframe 两种）、预填表单的属性、脚本在您页面上触发的事件，以及注册框的数据：等待确认的注册、已确认的注册和付费客户。在您的联盟申请获批之前，available 为 false。
权限： member
示例
curl https://privatusanalytics.com/account/affiliate/signup-box.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"theme": {
"type": "string",
"description": "注册框的主题：auto（匹配访问者的设备）、light 或 dark",
"enum": [
"auto",
"light",
"dark"
],
"examples": [
"auto"
],
"default": "auto"
}
},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "您是否拥有注册框（仅限已获批的联盟成员）"
},
"theme": {
"type": "string",
"description": "代码所针对的主题"
},
"frame_url": {
"anyOf": [
{
"type": "string",
"description": "注册框的地址，用于纯 iframe"
},
{
"type": "null"
}
]
},
"script": {
"anyOf": [
{
"type": "string",
"description": "脚本嵌入代码：一个元素和加载器脚本"
},
{
"type": "null"
}
]
},
"iframe": {
"anyOf": [
{
"type": "string",
"description": "纯 iframe 嵌入代码"
},
{
"type": "null"
}
]
},
"prefill_attributes": {
"type": "array",
"description": "元素上的属性，用于为已登录的访问者预填表单"
},
"events": {
"type": "array",
"description": "脚本在元素上触发的 DOM 事件"
},
"waiting": {
"type": "integer",
"description": "邮件中的链接尚未被打开的注册"
},
"signups": {
"type": "integer",
"description": "通过注册框完成的已确认注册"
},
"customers": {
"type": "integer",
"description": "其中成为付费客户的数量"
}
}
}
GET
/account/affiliate.json
获取您的联盟状态、推荐链接和统计数据
affiliate_get
您的联盟申请状态、推荐链接、您推荐的注册数和付费客户数，以及各币种的余额（保留中、可支付、已支付）。尚未申请时 status 为 none。
权限： member
示例
curl https://privatusanalytics.com/account/affiliate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "none（未申请）、pending、approved、rejected 或 suspended"
},
"code": {
"anyOf": [
{
"type": "string",
"description": "您的推荐码"
},
{
"type": "null"
}
]
},
"referral_url": {
"anyOf": [
{
"type": "string",
"description": "用于分享的链接（仅限已获批准的联盟成员）"
},
{
"type": "null"
}
]
},
"payout_method": {
"anyOf": [
{
"type": "string",
"description": "wise 或 credit"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "上一次申请被拒绝的原因"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "申请时间"
},
{
"type": "null"
}
]
},
"approved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "申请获批时间"
},
{
"type": "null"
}
]
},
"credit_blocked": {
"anyOf": [
{
"type": "string",
"description": "账户余额等待抵扣的原因：program（工作区处于折扣计划中）、no_subscription 或 no_workspace。没有阻碍时为 null"
},
{
"type": "null"
}
]
},
"signups": {
"type": "integer",
"description": "通过您的链接或推荐码创建的账户"
},
"customers": {
"type": "integer",
"description": "已付款的被推荐工作区"
},
"balances": {
"type": "array",
"description": "按币种：pending_cents（保留中）、approved_cents（可支付）和 paid_cents"
},
"payouts": {
"type": "array",
"description": "最近的支付记录，包含 amount_cents、currency、payout_method、status（applied：等待下次续订时抵扣的账户余额，或 paid）、applied_at 和 paid_at"
},
"terms": {
"type": "object",
"description": "佣金比例、月数、保留天数以及 Wise 支付门槛（以分为单位）"
}
}
}
营销活动
POST
/sites/:site_id/campaigns/costs.json
设置某营销活动在某月的花费
campaign_costs_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "该花费所属的 utm_campaign 值",
"examples": [
"spring_sale"
]
},
"month": {
"type": "string",
"description": "月份，YYYY-MM",
"examples": [
"2026-09"
]
},
"amount": {
"type": "number",
"description": "花费，以主要货币单位计，例如 1250.50"
},
"currency": {
"type": "string",
"description": "ISO 4217 货币（默认为站点货币）"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"campaign",
"month",
"amount",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本条目 ID"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小货币单位计的花费"
},
"currency": {
"type": "string",
"description": "金额的 ISO 4217 货币"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/campaigns/costs/:id.json
删除营销活动成本条目
campaign_costs_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/campaigns/costs/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本条目 ID"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小货币单位计的花费"
},
"currency": {
"type": "string",
"description": "金额的 ISO 4217 货币"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/campaigns/costs/import.json
从 CSV 导入营销活动成本（campaign,month,amount[,currency]）
campaign_costs_import
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/costs/import.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "CSV 文件上传（multipart 表单）"
},
"csv": {
"type": "string",
"description": "CSV 文本：campaign,month,amount[,currency]"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"imported": {
"type": "integer",
"description": "已保存的行数"
},
"failed": {
"type": "integer",
"description": "已跳过的行数"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "行被跳过的原因（前 50 条）"
}
}
}
GET
/sites/:site_id/campaigns/costs.json
列出营销活动成本条目
campaign_costs_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "仅显示此营销活动"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本条目 ID"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小货币单位计的花费"
},
"currency": {
"type": "string",
"description": "金额的 ISO 4217 货币"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/sites/:site_id/campaigns/costs/:id.json
更改营销活动成本条目
campaign_costs_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/campaigns/costs/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount": {
"type": "number",
"description": "花费，以主要货币单位计"
},
"currency": {
"type": "string",
"description": "ISO 4217 货币"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本条目 ID"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小货币单位计的花费"
},
"currency": {
"type": "string",
"description": "金额的 ISO 4217 货币"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/campaigns/builder.json
生成并验证带 UTM 标记的 URL
campaigns_builder
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns/builder.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"destination": {
"type": "string",
"description": "落地页 URL（https://…）",
"examples": [
"https://example.com/pricing"
]
},
"preset": {
"type": "string",
"description": "留空时为某个渠道填入 utm_source/utm_medium",
"enum": [
"newsletter",
"social",
"paid_search",
"paid_social",
"print",
"partner"
]
},
"utm_source": {
"type": "string",
"description": "流量来自哪里"
},
"utm_medium": {
"type": "string",
"description": "营销媒介，例如 email、cpc"
},
"utm_campaign": {
"type": "string",
"description": "营销活动名称，例如 spring_sale"
},
"utm_content": {
"type": "string",
"description": "变体，例如 header_button"
},
"utm_term": {
"type": "string",
"description": "付费搜索关键词"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"url": {
"anyOf": [
{
"type": "string",
"description": "带标记的 URL（有错误时为 null）"
},
{
"type": "null"
}
]
},
"valid": {
"type": "boolean",
"description": "没有错误时为 True"
},
"destination": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preset": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_source": {
"anyOf": [
{
"type": "string",
"description": "规范化后的 utm_source"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string",
"description": "规范化后的 utm_medium"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string",
"description": "规范化后的 utm_campaign"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string",
"description": "规范化后的 utm_content"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string",
"description": "规范化后的 utm_term"
},
{
"type": "null"
}
]
},
"issues": {
"type": "array",
"items": {
"type": "object"
},
"description": "field、level（error 或 warning）和 message"
},
"presets": {
"type": "object",
"description": "渠道预设：每个预设的 utm_source/utm_medium"
}
}
}
GET
/sites/:site_id/campaigns/hygiene.json
UTM 规范检查：近似重复值、样式问题和未知来源
campaigns_hygiene
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns/hygiene.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "周期的 from/to（UTC）"
},
"duplicates": {
"type": "array",
"items": {
"type": "object"
},
"description": "近似重复值：field、suggestion 和 variants [{value, visits}]"
},
"style_issues": {
"type": "array",
"items": {
"type": "object"
},
"description": "不是带下划线小写的值：field、value、visits、suggestion"
},
"unknown_sources": {
"type": "array",
"items": {
"type": "object"
},
"description": "我们无法识别的 utm_source 值：value、visits"
}
}
}
GET
/sites/:site_id/campaigns.json
营销活动汇总，含转化、收入、成本、CPA 和 ROAS
campaigns_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "日期范围预设。使用 custom 并配合 from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自定义范围的开始（站点时区）"
},
"to": {
"type": "string",
"format": "date",
"description": "自定义范围的结束，含当天"
},
"compare": {
"type": "string",
"description": "对比周期",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自定义对比的开始"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自定义对比的结束"
},
"match_weekday": {
"type": "boolean",
"description": "对齐对比的星期几",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "筛选条件：[[\"dimension\",\"operator\",\"value\"], …]。运算符：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。用 {\"any\": [...]} 包裹条件表示 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "应用已保存的细分（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入导入的历史数据（首个原生事件之前的日期，应用筛选条件或细分时会被忽略）",
"default": false
},
"goal_id": {
"type": "string",
"description": "要统计其转化的目标（goal_…）。默认为第一个启用的目标"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "周期的 from/to（UTC）"
},
"currency": {
"type": "string",
"description": "收入和成本使用的站点货币"
},
"goal_id": {
"anyOf": [
{
"type": "string",
"description": "计为转化的目标"
},
{
"type": "null"
}
]
},
"goal_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"campaigns": {
"type": "array",
"items": {
"type": "object"
},
"description": "每个 utm_campaign：visitors、visits、conversions、conversion_rate、revenue、cost、cpa（最小货币单位）、roas（收入 ÷ 成本）以及 sources [{source, medium, visitors, visits, conversions, conversion_rate, revenue}]"
},
"totals": {
"type": "object",
"description": "所有列出的营销活动的总和"
}
}
}
POST
/sites/:site_id/campaigns/links.json
将带 UTM 标记的链接保存到链接库
links_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "链接名称",
"examples": [
"Spring newsletter"
]
},
"destination": {
"type": "string",
"description": "落地页 URL（https://…）",
"examples": [
"https://example.com/pricing"
]
},
"utm_source": {
"type": "string",
"description": "utm_source 值（转为小写，空格变为下划线）"
},
"utm_medium": {
"type": "string",
"description": "utm_medium 值（转为小写，空格变为下划线）"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign 值（转为小写，空格变为下划线）"
},
"utm_content": {
"type": "string",
"description": "utm_content 值（转为小写，空格变为下划线）"
},
"utm_term": {
"type": "string",
"description": "utm_term 值（转为小写，空格变为下划线）"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "标签。以逗号分隔的值会被拆分",
"default": []
},
"notes": {
"type": "string",
"description": "自由文本备注"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"destination",
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "落地页 URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整带标记 URL"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/campaigns/links/:id.json
删除已保存的链接
links_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "落地页 URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整带标记 URL"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/campaigns/links.json
列出已保存的营销活动链接
links_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索名称、目标地址或营销活动"
},
"tag": {
"type": "string",
"description": "仅显示带此标签的链接"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "落地页 URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整带标记 URL"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/campaigns/links/:id/qr.json
已保存链接的二维码（SVG）
links_qr
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id/qr.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"size": {
"type": "integer",
"description": "模块大小（像素，2 到 20）",
"default": 6
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"link_id": {
"type": "string",
"description": "链接 ID"
},
"url": {
"type": "string",
"description": "已编码的（带标记的）URL"
},
"svg": {
"type": "string",
"description": "二维码的独立 SVG 文档"
}
}
}
GET
/sites/:site_id/campaigns/links/:id.json
获取已保存的营销活动链接
links_get
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "落地页 URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整带标记 URL"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/campaigns/links/:id.json
更改已保存的链接
links_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "链接名称",
"examples": [
"Spring newsletter"
]
},
"destination": {
"type": "string",
"description": "落地页 URL（https://…）",
"examples": [
"https://example.com/pricing"
]
},
"utm_source": {
"type": "string",
"description": "utm_source 值（转为小写，空格变为下划线）"
},
"utm_medium": {
"type": "string",
"description": "utm_medium 值（转为小写，空格变为下划线）"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign 值（转为小写，空格变为下划线）"
},
"utm_content": {
"type": "string",
"description": "utm_content 值（转为小写，空格变为下划线）"
},
"utm_term": {
"type": "string",
"description": "utm_term 值（转为小写，空格变为下划线）"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "标签。以逗号分隔的值会被拆分"
},
"notes": {
"type": "string",
"description": "自由文本备注"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "链接 ID，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "落地页 URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整带标记 URL"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
角色
POST
/workspaces/:workspace_id/roles.json
创建自定义角色
roles_create
权限： members.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/roles.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "角色名称",
"examples": [
"Client reviewer"
]
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "该角色授予的权限"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"permissions",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自定义角色 ID（成员上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "已授予的权限"
},
"members": {
"type": "integer",
"description": "拥有此角色的成员"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/roles/:id.json
删除自定义角色（必须未被使用）
roles_delete
权限： members.manage
示例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/roles/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自定义角色 ID（成员上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "已授予的权限"
},
"members": {
"type": "integer",
"description": "拥有此角色的成员"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/roles.json
列出自定义角色
roles_list
权限： member
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/roles.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自定义角色 ID（成员上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "已授予的权限"
},
"members": {
"type": "integer",
"description": "拥有此角色的成员"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/workspaces/:workspace_id/roles/:id.json
更新自定义角色
roles_update
权限： members.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/roles/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "角色名称"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "该角色授予的权限"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自定义角色 ID（成员上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "已授予的权限"
},
"members": {
"type": "integer",
"description": "拥有此角色的成员"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
警报
POST
/alerts/:id/acknowledge.json
确认最新事故
alerts_acknowledge
权限： analytics.read
示例
curl -X POST https://privatusanalytics.com/alerts/:id/acknowledge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/alerts.json
创建警报
alerts_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID（pa_…）。除用量警报外必填"
},
"metric": {
"type": "string",
"description": "threshold/anomaly：visitors、visits、pageviews、bounce_rate 或 conversion。vitals：lcp、inp、cls、fcp 或 ttfb"
},
"operator": {
"type": "string",
"description": "比较符（gt、gte、lt、lte）。anomaly：lt 仅针对下降，gt 仅针对激增，留空则两者皆是",
"enum": [
"gt",
"gte",
"lt",
"lte"
]
},
"threshold": {
"type": "number",
"description": "threshold：指标值，goal：完成数，no_data：小时数，usage：百分比，ssl：天数，vitals：毫秒（CLS：分数）"
},
"window_minutes": {
"type": "integer",
"description": "评估窗口，单位为分钟（5 到 10080）"
},
"sensitivity": {
"type": "string",
"description": "anomaly：low、medium 或 high",
"enum": [
"low",
"medium",
"high"
]
},
"goal_id": {
"type": "string",
"description": "goal 和 conversion 警报：目标 ID（goal_…）"
},
"uptime_check_id": {
"type": "string",
"description": "uptime/ssl：检查 ID（默认：站点的所有检查）"
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID（nch_…）"
},
"enabled": {
"type": "boolean",
"description": "评估此警报"
},
"name": {
"type": "string",
"description": "警报名称",
"examples": [
"Traffic dropped"
]
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"kind",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/alerts/:id.json
删除警报
alerts_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/alerts/:id/history.json
警报的事故历史
alerts_history
权限： analytics.read
示例
curl https://privatusanalytics.com/alerts/:id/history.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"open": {
"type": "boolean",
"description": "仅显示未解决的事故",
"default": false
},
"id": {
"type": "string",
"description": "资源的 Id"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"triggered_at": {
"type": "string",
"format": "date-time"
},
"resolved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"value": {
"anyOf": [
{
"type": "number",
"description": "触发时测得的值"
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"acknowledged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledged_by": {
"anyOf": [
{
"type": "string",
"description": "确认该事故的成员姓名"
},
{
"type": "null"
}
]
}
}
}
}
GET
/workspaces/:workspace_id/alerts.json
列出警报
alerts_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "仅显示此站点的警报（pa_…）"
},
"state": {
"type": "string",
"description": "仅显示 ok 或 triggered 的警报",
"enum": [
"ok",
"triggered"
]
},
"kind": {
"type": "string",
"description": "仅显示此类型",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/alerts/:id/mute.json
静音（或取消静音）警报通知
alerts_mute
权限： content.write
示例
curl -X POST https://privatusanalytics.com/alerts/:id/mute.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"minutes": {
"type": "integer",
"description": "静音的分钟数（0 为取消静音，最长 30 天）",
"default": 60
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/alerts/:id.json
获取警报
alerts_get
权限： analytics.read
示例
curl https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/alerts/:id.json
更新警报
alerts_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID（pa_…）。除用量警报外必填"
},
"metric": {
"type": "string",
"description": "threshold/anomaly：visitors、visits、pageviews、bounce_rate 或 conversion。vitals：lcp、inp、cls、fcp 或 ttfb"
},
"operator": {
"type": "string",
"description": "比较符（gt、gte、lt、lte）。anomaly：lt 仅针对下降，gt 仅针对激增，留空则两者皆是",
"enum": [
"gt",
"gte",
"lt",
"lte"
]
},
"threshold": {
"type": "number",
"description": "threshold：指标值，goal：完成数，no_data：小时数，usage：百分比，ssl：天数，vitals：毫秒（CLS：分数）"
},
"window_minutes": {
"type": "integer",
"description": "评估窗口，单位为分钟（5 到 10080）"
},
"sensitivity": {
"type": "string",
"description": "anomaly：low、medium 或 high",
"enum": [
"low",
"medium",
"high"
]
},
"goal_id": {
"type": "string",
"description": "goal 和 conversion 警报：目标 ID（goal_…）"
},
"uptime_check_id": {
"type": "string",
"description": "uptime/ssl：检查 ID（默认：站点的所有检查）"
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID（nch_…）"
},
"enabled": {
"type": "boolean",
"description": "评估此警报"
},
"name": {
"type": "string",
"description": "警报名称"
},
"kind": {
"type": "string",
"description": "警报类型",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/alerts.json
列出站点的警报
site_alerts_list
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "仅显示 ok 或 triggered 的警报",
"enum": [
"ok",
"triggered"
]
},
"kind": {
"type": "string",
"description": "仅显示此类型",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警报 ID，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "站点 ID（用量警报为 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 灵敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知渠道 ID"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
账单
POST
/workspaces/:workspace_id/billing/badge.json
选择加入或退出徽章奖励（免费套餐）
billing_badge
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/badge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "true 表示验证徽章并获得奖励"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"enabled",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付费档位每月的事件数"
},
"allowance": {
"type": "integer",
"description": "每月事件数，包含任何徽章奖励"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每个计费周期的美元价格"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "续订或结束时间"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
},
"description": "最近一次折扣计划申请，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已获批准计划对 Pro 和 Business 的折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章奖励（免费套餐）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
},
"description": "本月截至目前"
}
}
}
POST
/workspaces/:workspace_id/billing/cancel.json
在当前计费周期结束时取消
billing_cancel
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/cancel.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "取消的主要原因（可选调查）",
"enum": [
"too_expensive",
"missing_features",
"switching_tool",
"not_using",
"temporary",
"other"
]
},
"comment": {
"type": "string",
"description": "我们还有哪些可以改进的地方"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付费档位每月的事件数"
},
"allowance": {
"type": "integer",
"description": "每月事件数，包含任何徽章奖励"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每个计费周期的美元价格"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "续订或结束时间"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
},
"description": "最近一次折扣计划申请，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已获批准计划对 Pro 和 Business 的折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章奖励（免费套餐）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
},
"description": "本月截至目前"
}
}
}
POST
/workspaces/:workspace_id/billing/change_plan.json
更改套餐、档位或周期（按比例计费）
billing_change_plan
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/change_plan.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "要切换到的套餐：pro 或 business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "该档位每月的事件数，来自 GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "计费周期。按年付费免费获得 2 个月",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付费档位每月的事件数"
},
"allowance": {
"type": "integer",
"description": "每月事件数，包含任何徽章奖励"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每个计费周期的美元价格"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "续订或结束时间"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
},
"description": "最近一次折扣计划申请，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已获批准计划对 Pro 和 Business 的折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章奖励（免费套餐）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
},
"description": "本月截至目前"
}
}
}
POST
/workspaces/:workspace_id/billing/checkout.json
为付费套餐发起 Paddle 结账
billing_checkout
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/checkout.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "要切换到的套餐：pro 或 business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "该档位每月的事件数，来自 GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "计费周期。按年付费免费获得 2 个月",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Paddle 交易 ID（txn_...）"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "托管结账 URL"
},
{
"type": "null"
}
]
},
"price_id": {
"type": "string"
},
"plan": {
"type": "string"
},
"events": {
"type": "integer"
},
"interval": {
"type": "string"
},
"amount": {
"type": "integer",
"description": "每个周期的美元金额"
},
"client_token": {
"anyOf": [
{
"type": "string",
"description": "Paddle.js 客户端令牌"
},
{
"type": "null"
}
]
},
"environment": {
"type": "string",
"description": "sandbox 或 production"
},
"custom_data": {
"type": "object",
"description": "传给 Paddle 以关联订阅"
},
"discount_id": {
"anyOf": [
{
"type": "string",
"description": "已获批准计划的 Paddle 折扣 ID，应用于本次结账"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/discount.json
申请非营利、教育或开源折扣
billing_discount
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/discount.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source（5 折）、open_source_free（每月最多 100 万个事件的免费 Pro）或 agency（您拥有的每个工作区 8 折）",
"enum": [
"nonprofit",
"education",
"open_source",
"open_source_free",
"agency"
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构的名称"
},
"website": {
"type": "string",
"description": "其网站"
},
"proof_url": {
"type": "string",
"description": "证明链接。开源项目请填写代码仓库 URL"
},
"license": {
"type": "string",
"description": "项目的 OSI 许可证（仅限开源）"
},
"note": {
"type": "string",
"description": "任何有助于审核的信息，最多 1,000 个字符"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"program",
"organization_name",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/payment_method.json
获取更新付款方式的链接
billing_payment_method
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/payment_method.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal、payment_method 或 invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "短期有效的 Paddle URL"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/portal.json
获取 Paddle 客户门户链接
billing_portal
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/portal.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal、payment_method 或 invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "短期有效的 Paddle URL"
},
{
"type": "null"
}
]
}
}
}
GET
/workspaces/:workspace_id/billing/preview.json
预览套餐变更及按比例计费
billing_preview
权限： billing.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "要切换到的套餐：pro 或 business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "该档位每月的事件数，来自 GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "计费周期。按年付费免费获得 2 个月",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"events": {
"type": "integer"
},
"interval": {
"type": "string"
},
"price_id": {
"type": "string"
},
"amount": {
"type": "integer",
"description": "每个周期的新价格（美元）"
},
"currency": {
"type": "string"
},
"charge_minor": {
"type": "integer",
"description": "现在收取的金额，以最小货币单位计"
},
"credit_minor": {
"type": "integer",
"description": "未使用时间的抵扣额，以最小货币单位计"
},
"result_action": {
"anyOf": [
{
"type": "string",
"description": "charge 或 credit"
},
{
"type": "null"
}
]
},
"result_minor": {
"type": "integer",
"description": "净收费或抵扣额，以最小货币单位计"
},
"next_billed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "新套餐无法覆盖的用量或限额"
}
}
}
POST
/workspaces/:workspace_id/billing/resume.json
撤销已计划的取消或恢复暂停
billing_resume
权限： billing.manage
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/resume.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付费档位每月的事件数"
},
"allowance": {
"type": "integer",
"description": "每月事件数，包含任何徽章奖励"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每个计费周期的美元价格"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "续订或结束时间"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
},
"description": "最近一次折扣计划申请，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已获批准计划对 Pro 和 Business 的折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章奖励（免费套餐）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
},
"description": "本月截至目前"
}
}
}
GET
/workspaces/:workspace_id/billing.json
获取套餐、订阅和用量
billing_get
权限： billing.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付费档位每月的事件数"
},
"allowance": {
"type": "integer",
"description": "每月事件数，包含任何徽章奖励"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每个计费周期的美元价格"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "续订或结束时间"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
},
"description": "最近一次折扣计划申请，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已获批准计划对 Pro 和 Business 的折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章奖励（免费套餐）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
},
"description": "本月截至目前"
}
}
}
PATCH
/workspaces/:workspace_id/billing.json
更新账单邮箱、税号和自动升级
billing_update
权限： billing.manage
示例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/billing.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"billing_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "用于接收发票和账单通知的额外地址（最多 5 个）"
},
"tax_id": {
"type": "string",
"description": "显示在发票上的 VAT/GST/税号"
},
"auto_upgrade": {
"type": "boolean",
"description": "为 true 时，达到每月上限后会升到下一档位并收取差价，而不是暂停采集。默认关闭"
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付费档位每月的事件数"
},
"allowance": {
"type": "integer",
"description": "每月事件数，包含任何徽章奖励"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每个计费周期的美元价格"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "续订或结束时间"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未应用到订阅）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 和 Business 的折扣百分比（免费开源计划为 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免费事件数（仅限免费开源计划）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "组织、学校、项目或代理机构名称"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "网站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "证明链接或代码仓库 URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 许可证（开源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "给审核人员的说明"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申请未获批准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申请时间"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "审核时间"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效时间"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "计划结束时间"
},
{
"type": "null"
}
]
}
},
"description": "最近一次折扣计划申请，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已获批准计划对 Pro 和 Business 的折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章奖励（免费套餐）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
},
"description": "本月截至目前"
}
}
}
GET
/workspaces/:workspace_id/billing/usage.json
获取本月用量、预测和各站点分布
billing_usage
权限： billing.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/usage.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "要报告的月份中的任意一天（默认为本月）",
"examples": [
"2026-09-01"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所报告月份的第一天"
},
"events": {
"type": "integer",
"description": "计费事件（浏览量和自定义事件）"
},
"bots": {
"type": "integer",
"description": "被过滤掉的机器人请求（不计费）"
},
"allowance": {
"type": "integer",
"description": "包含的事件数，含徽章奖励"
},
"percent": {
"type": "number",
"description": "事件数占额度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "预计月底的事件数"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩余天数"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（过去某个月达到或超过额度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的浏览量和自定义事件"
},
"share": {
"type": "number",
"description": "占工作区总量的百分比"
}
}
},
"description": "按站点统计的事件数"
},
"history": {
"type": "array",
"description": "之前的月份，最新的在前"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "仪表板被 Privatus Analytics 工作人员锁定的起始时间"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被丢弃期间为 true（已达到每月上限，或工作人员暂停了采集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "采集暂停的原因：limit（已达到每月额度）或 staff。正在采集时为 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "工作人员暂停采集的时间"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因上限而暂停的解除时间：下个月初（UTC），升级则更早。其他情况为 null"
},
{
"type": "null"
}
]
}
}
}
GET
/workspaces/:workspace_id/billing/invoices.json
列出发票
billing_invoices_list
权限： billing.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/invoices.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Paddle 交易 ID"
},
"invoice_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "paid、completed、payment_failed，..."
},
"amount_minor": {
"type": "integer",
"description": "以最小货币单位（分）计的总额"
},
"currency": {
"type": "string"
},
"billed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
}
}
}
GET
/workspaces/:workspace_id/billing/invoices/:id.json
获取发票的 PDF 链接
billing_invoices_get
权限： billing.manage
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/invoices/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal、payment_method 或 invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "短期有效的 Paddle URL"
},
{
"type": "null"
}
]
}
}
}
账户
GET
/account.json
获取您的个人资料和偏好设置
account_get
权限： member
示例
curl https://privatusanalytics.com/account.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"unconfirmed_email": {
"anyOf": [
{
"type": "string",
"description": "等待确认的新邮箱"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"theme": {
"type": "string"
},
"default_landing": {
"type": "string"
},
"locale": {
"type": "string",
"description": "此账户的应用语言代码（默认为 en）"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shortcuts_enabled": {
"type": "boolean"
},
"reduce_motion": {
"type": "boolean"
},
"product_emails": {
"type": "boolean"
},
"marketing_emails": {
"type": "boolean",
"description": "是否可以发送营销邮件（系列邮件）。取消订阅后为 false"
},
"newsletter": {
"type": "boolean"
},
"two_factor": {
"type": "boolean"
},
"passkeys": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/account.json
更新您的个人资料和偏好设置
account_update
权限： member
示例
curl -X PATCH https://privatusanalytics.com/account.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "您的姓名"
},
"email": {
"type": "string",
"description": "新的邮箱地址（需先通过邮件确认）"
},
"theme": {
"type": "string",
"description": "颜色主题",
"enum": [
"system",
"light",
"dark"
]
},
"default_landing": {
"type": "string",
"description": "登录后的页面：sites 或 last_site",
"enum": [
"sites",
"last_site"
]
},
"locale": {
"type": "string",
"description": "登录后应用的语言，使用语言代码（en、de、fr 等）。公开页面和 API 保持不变",
"enum": [
"en",
"de",
"es",
"fr",
"it",
"nl",
"pt",
"pl",
"sv",
"da",
"no",
"fi",
"ja",
"ko",
"zh-CN",
"zh-TW"
]
},
"timezone": {
"type": "string",
"description": "您的时区（IANA 名称）"
},
"shortcuts_enabled": {
"type": "boolean",
"description": "键盘快捷键"
},
"reduce_motion": {
"type": "boolean",
"description": "减少动画"
},
"product_emails": {
"type": "boolean",
"description": "产品更新和使用技巧邮件"
},
"marketing_emails": {
"type": "boolean",
"description": "营销邮件，例如入门提示。取消订阅后要重新开启，需要使用已登录的浏览器"
},
"newsletter": {
"type": "boolean",
"description": "每月新闻通讯"
}
},
"required": []
}
响应数据
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"unconfirmed_email": {
"anyOf": [
{
"type": "string",
"description": "等待确认的新邮箱"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"theme": {
"type": "string"
},
"default_landing": {
"type": "string"
},
"locale": {
"type": "string",
"description": "此账户的应用语言代码（默认为 en）"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shortcuts_enabled": {
"type": "boolean"
},
"reduce_motion": {
"type": "boolean"
},
"product_emails": {
"type": "boolean"
},
"marketing_emails": {
"type": "boolean",
"description": "是否可以发送营销邮件（系列邮件）。取消订阅后为 false"
},
"newsletter": {
"type": "boolean"
},
"two_factor": {
"type": "boolean"
},
"passkeys": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
跟踪
POST
/sites/:site_id/tracking/ingest_key.json
创建或轮换服务器采集密钥（只显示一次）
tracking_ingest_key_rotate
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/tracking/ingest_key.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID"
},
"key": {
"type": "string",
"description": "采集密钥。只显示一次：请立即保存。将其作为 Bearer 令牌发送到 POST /api/events"
},
"prefix": {
"type": "string",
"description": "设置中显示的密钥前缀"
}
}
}
DELETE
/sites/:site_id/tracking/ingest_key.json
撤销服务器采集密钥
tracking_ingest_key_revoke
权限： sites.manage
示例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/tracking/ingest_key.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "跟踪代码片段中使用的站点 ID"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "服务器采集密钥的开头"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 跟踪代码片段"
},
"favorite": {
"type": "boolean",
"description": "已被您加星标"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/tracking/verify.json
检查站点是否已安装跟踪器（script 标签、站点 ID、CSP 和 referrer 策略）
tracking_verify
权限： sites.manage
示例
curl -X POST https://privatusanalytics.com/sites/:site_id/tracking/verify.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要检查的页面（默认为 https://<domain>/）"
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
GET
/sites/:site_id/tracking/snippet.json
根据所选选项生成跟踪代码片段
tracking_snippet
权限： analytics.read
示例
curl https://privatusanalytics.com/sites/:site_id/tracking/snippet.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"modules": {
"type": "array",
"items": {
"type": "string"
},
"description": "可选模块：auto（外部链接、下载、表单、404）、engage（时间和滚动）、vitals（网页性能指标）、clicks",
"default": [
"engage"
]
},
"manual": {
"type": "boolean",
"description": "关闭自动浏览量",
"default": false
},
"spa": {
"type": "string",
"description": "单页应用导航跟踪",
"enum": [
"auto",
"history",
"hash",
"off"
],
"default": "auto"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "仅在这些主机名上跟踪",
"default": []
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "不跟踪的路径 glob，例如 /admin/*",
"default": []
},
"query_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "要额外保留的查询参数，例如 page",
"default": []
},
"mask": {
"type": "array",
"items": {
"type": "string"
},
"description": "客户端路径遮蔽，例如 /u/*->/u/:id",
"default": []
},
"site_id": {
"type": "string",
"description": "站点 ID，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
响应数据
{
"type": "object"
}
通知渠道
POST
/workspaces/:workspace_id/channels.json
添加通知渠道
notification_channels_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/channels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook URL（slack、teams、discord、webhook），HTTPS"
},
"secret": {
"type": "string",
"description": "webhook：X-Privatus-Signature 的 HMAC 密钥"
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "email：收件人地址（最多 20 个）"
},
"routing_key": {
"type": "string",
"description": "pagerduty：Events API v2 集成密钥"
},
"api_key": {
"type": "string",
"description": "opsgenie：API 集成密钥"
},
"region": {
"type": "string",
"description": "opsgenie：账户区域",
"enum": [
"us",
"eu"
]
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push",
"enum": [
"email",
"slack",
"teams",
"discord",
"webhook",
"pagerduty",
"opsgenie",
"push"
]
},
"name": {
"type": "string",
"description": "显示名称",
"examples": [
"#alerts"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"kind",
"name",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "渠道 ID，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/channels/:id.json
删除通知渠道
notification_channels_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "渠道 ID，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/channels.json
列出通知渠道
notification_channels_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/channels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "仅显示此类型的渠道",
"enum": [
"email",
"slack",
"teams",
"discord",
"webhook",
"pagerduty",
"opsgenie",
"push"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "渠道 ID，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/channels/:id/send_test.json
通过渠道发送测试消息
notification_channels_send_test
权限： content.write
示例
curl -X POST https://privatusanalytics.com/channels/:id/send_test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "渠道 ID，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/channels/:id.json
获取通知渠道
notification_channels_get
权限： analytics.read
示例
curl https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "渠道 ID，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/channels/:id.json
更新通知渠道
notification_channels_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook URL（slack、teams、discord、webhook），HTTPS"
},
"secret": {
"type": "string",
"description": "webhook：X-Privatus-Signature 的 HMAC 密钥"
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "email：收件人地址（最多 20 个）"
},
"routing_key": {
"type": "string",
"description": "pagerduty：Events API v2 集成密钥"
},
"api_key": {
"type": "string",
"description": "opsgenie：API 集成密钥"
},
"region": {
"type": "string",
"description": "opsgenie：账户区域",
"enum": [
"us",
"eu"
]
},
"name": {
"type": "string",
"description": "显示名称"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "渠道 ID，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/push_subscription.json
注册浏览器以接收推送通知
push_subscriptions_create
权限： member
示例
curl -X POST https://privatusanalytics.com/push_subscription.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"description": "浏览器的 PushSubscription.endpoint"
},
"p256dh": {
"type": "string",
"description": "PushSubscription keys.p256dh（base64url）"
},
"auth": {
"type": "string",
"description": "PushSubscription keys.auth（base64url）"
}
},
"required": [
"endpoint",
"p256dh",
"auth"
]
}
响应数据
{
"type": "object",
"properties": {
"endpoint_host": {
"type": "string",
"description": "推送服务主机"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/push_subscription.json
移除浏览器推送注册
push_subscriptions_delete
权限： member
示例
curl -X DELETE https://privatusanalytics.com/push_subscription.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"description": "要移除的 PushSubscription.endpoint"
}
},
"required": [
"endpoint"
]
}
响应数据
{
"type": "object",
"properties": {
"endpoint_host": {
"type": "string",
"description": "推送服务主机"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
邮件报告
DELETE
/recipients/:id.json
从邮件报告中移除收件人
email_report_recipients_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/recipients/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
}
GET
/reports/:report_id/recipients.json
列出邮件报告的收件人及其状态
email_report_recipients_list
状态：active（接收报告）、pending（已邀请，尚未接受）、declined 或 unsubscribed。通过报告的收件人列表添加或移除地址。
权限： analytics.read
示例
curl https://privatusanalytics.com/reports/:report_id/recipients.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅返回此状态的收件人",
"enum": [
"pending",
"active",
"declined",
"unsubscribed"
]
},
"report_id": {
"type": "string",
"description": "资源的 Report"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"report_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
}
}
POST
/recipients/:id/resend.json
重新发送待处理的报告邀请
email_report_recipients_resend
使用新链接再次发送邀请。每份报告的每个地址每 7 天可发送一次。
权限： content.write
示例
curl -X POST https://privatusanalytics.com/recipients/:id/resend.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/reports.json
创建邮件报告
email_reports_create
权限： content.write
示例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/reports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告包含的站点 ID（pa_…）"
},
"frequency": {
"type": "string",
"description": "daily、weekly（在星期几）或 monthly（每月 1 日）",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"hour": {
"type": "integer",
"description": "发送的小时（0 到 23，工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周报告：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "邮箱地址（无需账户）。条目可用逗号或换行分隔。工作区成员会立即添加。其他人会收到邀请，接受后才会收到报告。已退订报告的地址会被拒绝"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容：kpis、chart、pages、sources、goals、campaigns、vitals、uptime"
},
"attach_pdf": {
"type": "boolean",
"description": "附上 PDF 版本"
},
"intro": {
"type": "string",
"description": "自定义介绍文字（最多 2000 个字符）"
},
"enabled": {
"type": "boolean",
"description": "按计划发送"
},
"name": {
"type": "string",
"description": "报告名称",
"examples": [
"Weekly traffic"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "报告 ID，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告中的站点 ID"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "发送小时（工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告上的所有地址，不论状态"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其订阅状态（只有 active 的收件人会收到报告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容块"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/reports/:id/deliveries.json
邮件报告的投递日志
email_reports_deliveries
权限： analytics.read
示例
curl https://privatusanalytics.com/reports/:id/deliveries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "仅显示此状态的投递",
"enum": [
"sent",
"test",
"failed",
"skipped"
]
},
"id": {
"type": "string",
"description": "资源的 Id"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "sent、test、failed 或 skipped"
},
"recipients_count": {
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
}
}
DELETE
/reports/:id.json
删除邮件报告
email_reports_delete
权限： content.write
示例
curl -X DELETE https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "报告 ID，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告中的站点 ID"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "发送小时（工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告上的所有地址，不论状态"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其订阅状态（只有 active 的收件人会收到报告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容块"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/reports.json
列出邮件报告
email_reports_list
权限： analytics.read
示例
curl https://privatusanalytics.com/workspaces/:workspace_id/reports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "仅显示此频率的报告",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"workspace_id": {
"type": "string",
"description": "工作区 ID，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "页码（从 1 开始）"
},
"per_page": {
"type": "integer",
"description": "每页结果数（最多 100）"
}
},
"required": [
"workspace_id"
]
}
响应数据
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "报告 ID，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告中的站点 ID"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "发送小时（工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告上的所有地址，不论状态"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其订阅状态（只有 active 的收件人会收到报告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容块"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/reports/:id/send_test.json
立即发送一封邮件报告作为测试
email_reports_send_test
权限： content.write
示例
curl -X POST https://privatusanalytics.com/reports/:id/send_test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "将测试发送到此处（默认：您的邮箱）"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "sent、test、failed 或 skipped"
},
"recipients_count": {
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/reports/:id.json
获取邮件报告
email_reports_get
权限： analytics.read
示例
curl https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"输入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "报告 ID，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告中的站点 ID"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "发送小时（工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告上的所有地址，不论状态"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其订阅状态（只有 active 的收件人会收到报告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容块"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/reports/:id.json
更新邮件报告
email_reports_update
权限： content.write
示例
curl -X PATCH https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告包含的站点 ID（pa_…）"
},
"frequency": {
"type": "string",
"description": "daily、weekly（在星期几）或 monthly（每月 1 日）",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"hour": {
"type": "integer",
"description": "发送的小时（0 到 23，工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周报告：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "邮箱地址（无需账户）。条目可用逗号或换行分隔。工作区成员会立即添加。其他人会收到邀请，接受后才会收到报告。已退订报告的地址会被拒绝"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容：kpis、chart、pages、sources、goals、campaigns、vitals、uptime"
},
"attach_pdf": {
"type": "boolean",
"description": "附上 PDF 版本"
},
"intro": {
"type": "string",
"description": "自定义介绍文字（最多 2000 个字符）"
},
"enabled": {
"type": "boolean",
"description": "按计划发送"
},
"name": {
"type": "string",
"description": "报告名称"
},
"id": {
"type": "string",
"description": "资源的 Id"
}
},
"required": [
"id"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "报告 ID，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告中的站点 ID"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "发送小时（工作区时区）"
},
"weekday": {
"type": "integer",
"description": "每周：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "报告上的所有地址，不论状态"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其订阅状态（只有 active 的收件人会收到报告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "内容块"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/reports/invites/:token/accept.json
接受报告邀请
report_invites_accept
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/reports/invites/:token/accept.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
}
POST
/reports/invites/:token/decline.json
拒绝报告邀请
report_invites_decline
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/reports/invites/:token/decline.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 ID，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "邮箱地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上一次发送邀请的时间"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待处理邀请的过期时间"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "该地址变为 active 的时间"
},
{
"type": "null"
}
]
}
}
}
POST
/reports/resubscribe/:token.json
退订后重新接收报告
report_resubscribes_confirm
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/reports/resubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object"
}
POST
/reports/unsubscribe/:token/resubscribe.json
向某个地址发送重新接收报告的链接
report_resubscribes_create
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/reports/unsubscribe/:token/resubscribe.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object"
}
POST
/reports/unsubscribe/:token.json
将某个地址从邮件报告中退订
report_unsubscribes_create
权限： public
· 仅限 HTTP（不是 MCP 工具）
示例
curl -X POST https://privatusanalytics.com/reports/unsubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'输入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "资源的 Token"
}
},
"required": [
"token"
]
}
响应数据
{
"type": "object"
}