plausible

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plausible Analytics API

Query website analytics and manage sites with Plausible's privacy-friendly analytics platform.

通过Plausible这款注重隐私的分析平台，查询网站分析数据并管理站点。

When to Use

适用场景

Query visitor statistics and pageviews
Analyze traffic sources and referrers
Get geographic and device breakdowns
Track conversions and goals
Manage analytics sites programmatically

查询访客统计数据与页面浏览量
分析流量来源与引荐链接
获取地域分布及设备类型细分数据
追踪转化与目标完成情况
以编程方式管理分析站点

Prerequisites

前置条件

bash

export PLAUSIBLE_API_KEY=your-api-key
export PLAUSIBLE_SITE_ID=example.com

bash

export PLAUSIBLE_API_KEY=your-api-key
export PLAUSIBLE_SITE_ID=example.com

Get API Key

获取API密钥

Log in to Plausible: https://plausible.io/login
Go to Account Settings (top-right menu)
Navigate to "API Keys" in sidebar
Click "New API Key"
Choose key type:

Stats API - For querying analytics data
Sites API - For managing sites programmatically

Save the key (shown only once)

Important: When using
$VAR
in a command that pipes to another command, wrap the command containing
$VAR
in
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

登录Plausible：https://plausible.io/login
进入账户设置（右上角菜单）
在侧边栏中找到「API Keys」
点击「New API Key」
选择密钥类型：

Stats API - 用于查询分析数据
Sites API - 用于以编程方式管理站点

保存密钥（仅显示一次）

重要提示：当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

Stats API (v2)

Basic Query - Total Visitors

基础查询 - 总访客数

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "7d"
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Docs: https://plausible.io/docs/stats-api

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "7d"
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

文档：https://plausible.io/docs/stats-api

Query with Dimensions (Breakdown)

带维度的查询（细分）

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "30d",
  "dimensions": ["visit:source"]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "30d",
  "dimensions": ["visit:source"]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Top Pages

Geographic Breakdown

地域分布数据

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors"],
  "date_range": "30d",
  "dimensions": ["visit:country_name", "visit:city_name"]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors"],
  "date_range": "30d",
  "dimensions": ["visit:country_name", "visit:city_name"]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Device & Browser Stats

设备与浏览器统计

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors"],
  "date_range": "7d",
  "dimensions": ["visit:device"]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors"],
  "date_range": "7d",
  "dimensions": ["visit:device"]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Time Series (Daily)

时间序列（按日）

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "30d",
  "dimensions": ["time:day"]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "30d",
  "dimensions": ["time:day"]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Filter by Page Path

按页面路径过滤

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "7d",
  "filters": [["contains", "event:page", ["/blog"]]]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "7d",
  "filters": [["contains", "event:page", ["/blog"]]]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

UTM Campaign Analysis

UTM推广活动分析

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "conversion_rate"],
  "date_range": "30d",
  "dimensions": ["visit:utm_source", "visit:utm_campaign"]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "conversion_rate"],
  "date_range": "30d",
  "dimensions": ["visit:utm_source", "visit:utm_campaign"]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Custom Date Range

自定义日期范围

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": ["2024-01-01", "2024-01-31"]
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": ["2024-01-01", "2024-01-31"]
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Site Provisioning API

站点配置API

List Sites

列出所有站点

bash

bash -c 'curl -s -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites"'

Docs: https://plausible.io/docs/sites-api

bash

bash -c 'curl -s -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites"'

文档：https://plausible.io/docs/sites-api

Create Site

创建站点

Write to

/tmp/plausible_request.json

json

{
  "domain": "newsite.com",
  "timezone": "America/New_York"
}

Then run:

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v1/sites" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "domain": "newsite.com",
  "timezone": "America/New_York"
}

然后执行：

bash

bash -c 'curl -s -X POST "https://plausible.io/api/v1/sites" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Get Site Details

获取站点详情

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites/<your-site-id>"'

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites/<your-site-id>"'

Delete Site

删除站点

Warning: This will permanently delete the site and all its data.

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X DELETE -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites/<your-site-id>"'

警告：此操作将永久删除该站点及其所有数据。

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X DELETE -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites/<your-site-id>"'

Create Goal

创建目标

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "goal_type": "event",
  "event_name": "Signup"
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X PUT "https://plausible.io/api/v1/sites/goals" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "goal_type": "event",
  "event_name": "Signup"
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X PUT "https://plausible.io/api/v1/sites/goals" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Create Page Goal

创建页面目标

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "goal_type": "page",
  "page_path": "/thank-you"
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X PUT "https://plausible.io/api/v1/sites/goals" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "goal_type": "page",
  "page_path": "/thank-you"
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X PUT "https://plausible.io/api/v1/sites/goals" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

List Goals

列出所有目标

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites/goals?site_id=<your-site-id>"'

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -H "Authorization: Bearer $PLAUSIBLE_API_KEY" "https://plausible.io/api/v1/sites/goals?site_id=<your-site-id>"'

Create Shared Link

创建共享链接

Write to

/tmp/plausible_request.json

json

{
  "site_id": "<your-site-id>",
  "name": "Public Dashboard"
}

Replace

<your-site-id>

with your actual site ID (typically your domain like "example.com"):

bash

bash -c 'curl -s -X PUT "https://plausible.io/api/v1/sites/shared-links" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

将以下内容写入

/tmp/plausible_request.json

：

json

{
  "site_id": "<your-site-id>",
  "name": "Public Dashboard"
}

替换

<your-site-id>

为实际的站点ID（通常是你的域名，如"example.com"）：

bash

bash -c 'curl -s -X PUT "https://plausible.io/api/v1/sites/shared-links" -H "Authorization: Bearer $PLAUSIBLE_API_KEY" -H "Content-Type: application/json" -d @/tmp/plausible_request.json'

Available Metrics

可用指标

Metric	Type	Description
`visitors`	int	Unique visitors
`visits`	int	Total sessions
`pageviews`	int	Page views
`bounce_rate`	float	Bounce rate (%)
`visit_duration`	int	Avg duration (seconds)
`views_per_visit`	float	Pages per session
`conversion_rate`	float	Goal conversion rate (requires goal to be configured)
`events`	int	Total events

Note: The
conversion_rate
metric requires at least one goal to be configured for your site. Create a goal first using the "Create Goal" or "Create Page Goal" endpoints before querying conversion rates.

指标	类型	描述
`visitors`	int	独立访客数
`visits`	int	总会话数
`pageviews`	int	页面浏览量
`bounce_rate`	float	跳出率（%）
`visit_duration`	int	平均会话时长（秒）
`views_per_visit`	float	每次会话浏览页面数
`conversion_rate`	float	目标转化率（需先配置目标）
`events`	int	总事件数

注意：
conversion_rate
指标要求你的站点至少配置一个目标。在查询转化率之前，请先使用「创建目标」或「创建页面目标」接口添加目标。

Available Dimensions

可用维度

Event Dimensions

事件维度

```
event:goal
```
- Custom goals
```
event:page
```
- Page path
```
event:hostname
```
- Hostname

```
event:goal
```
- 自定义目标
```
event:page
```
- 页面路径
```
event:hostname
```
- 主机名

Visit Dimensions

访问维度

```
visit:source
```
- Traffic source
```
visit:referrer
```
- Full referrer URL
```
visit:utm_source
```
- UTM source
```
visit:utm_medium
```
- UTM medium
```
visit:utm_campaign
```
- UTM campaign
```
visit:country_name
```
- Country
```
visit:region_name
```
- Region/State
```
visit:city_name
```
- City
```
visit:device
```
- Device type
```
visit:browser
```
- Browser name
```
visit:browser_version
```
- Browser version
```
visit:os
```
- Operating system
```
visit:os_version
```
- OS version

```
visit:source
```
- 流量来源
```
visit:referrer
```
- 完整引荐链接URL
```
visit:utm_source
```
- UTM来源
```
visit:utm_medium
```
- UTM媒介
```
visit:utm_campaign
```
- UTM推广活动
```
visit:country_name
```
- 国家
```
visit:region_name
```
- 地区/州
```
visit:city_name
```
- 城市
```
visit:device
```
- 设备类型
```
visit:browser
```
- 浏览器名称
```
visit:browser_version
```
- 浏览器版本
```
visit:os
```
- 操作系统
```
visit:os_version
```
- 操作系统版本

Time Dimensions

时间维度

```
time
```
- Auto granularity
```
time:hour
```
- Hourly
```
time:day
```
- Daily
```
time:week
```
- Weekly
```
time:month
```
- Monthly

```
time
```
- 自动粒度
```
time:hour
```
- 按小时
```
time:day
```
- 按天
```
time:week
```
- 按周
```
time:month
```
- 按月

Filter Operators

过滤运算符

Operator	Description
`is`	Equals any value
`is_not`	Not equals
`contains`	Contains substring
`matches`	Regex match

运算符	描述
`is`	等于任意指定值
`is_not`	不等于
`contains`	包含指定子串
`matches`	正则匹配

Complex Filters

复杂过滤

json

["and", [
  ["is", "visit:country_name", ["United States"]],
  ["contains", "event:page", ["/blog"]]
]]

json

["and", [
  ["is", "visit:country_name", ["United States"]],
  ["contains", "event:page", ["/blog"]]
]]

Date Range Options

日期范围选项

Value	Description
`day`	Today
`7d`	Last 7 days
`28d`	Last 28 days
`30d`	Last 30 days
`month`	Current month
`6mo`	Last 6 months
`12mo`	Last 12 months
`year`	Current year
`all`	All time
`["2024-01-01", "2024-12-31"]`	Custom range

值	描述
`day`	今天
`7d`	过去7天
`28d`	过去28天
`30d`	过去30天
`month`	当前月份
`6mo`	过去6个月
`12mo`	过去12个月
`year`	当前年份
`all`	所有时间
`["2024-01-01", "2024-12-31"]`	自定义范围

Rate Limits

请求频率限制

600 requests per hour per API key

每个API密钥每小时最多600次请求

API Reference

API参考文档

Stats API: https://plausible.io/docs/stats-api
Sites API: https://plausible.io/docs/sites-api
Main Docs: https://plausible.io/docs

Stats API: https://plausible.io/docs/stats-api
Sites API: https://plausible.io/docs/sites-api
主文档: https://plausible.io/docs

plausible

Original

Translation

Plausible Analytics API

Plausible Analytics API

When to Use

适用场景

Prerequisites

前置条件

Get API Key

获取API密钥

Stats API (v2)

Stats API (v2)

Basic Query - Total Visitors

基础查询 - 总访客数

Query with Dimensions (Breakdown)

带维度的查询（细分）

Top Pages

热门页面

Geographic Breakdown

地域分布数据

Device & Browser Stats

设备与浏览器统计

Time Series (Daily)

时间序列（按日）

Filter by Page Path

按页面路径过滤

UTM Campaign Analysis

UTM推广活动分析

Custom Date Range

自定义日期范围

Site Provisioning API

站点配置API

List Sites

列出所有站点

Create Site

创建站点

Get Site Details

获取站点详情

Delete Site

删除站点

Create Goal

创建目标

Create Page Goal

创建页面目标

List Goals

列出所有目标

Create Shared Link

创建共享链接

Available Metrics

可用指标

Available Dimensions

可用维度

Event Dimensions

事件维度

Visit Dimensions

访问维度

Time Dimensions

时间维度

Filter Operators

过滤运算符

Complex Filters

复杂过滤

Date Range Options

日期范围选项

Rate Limits

请求频率限制

API Reference

API参考文档