Back to Details

plausible

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plausible Analytics API

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密钥

  1. Log in to Plausible: https://plausible.io/login
  2. Go to Account Settings (top-right menu)
  3. Navigate to "API Keys" in sidebar
  4. Click "New API Key"
  5. Choose key type:
  • Stats API - For querying analytics data
  • Sites API - For managing sites programmatically
  1. 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 .
  1. 登录Plausible：https://plausible.io/login
  2. 进入账户设置（右上角菜单）
  3. 在侧边栏中找到「API Keys」
  4. 点击「New API Key」
  5. 选择密钥类型：
  • Stats API - 用于查询分析数据
  • Sites API - 用于以编程方式管理站点
  1. 保存密钥（仅显示一次）
重要提示：当在包含管道的命令中使用
$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)

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

热门页面

Write to 
/tmp/plausible_request.json
:
json
{
  "site_id": "<your-site-id>",
  "metrics": ["visitors", "pageviews"],
  "date_range": "7d",
  "dimensions": ["event:page"],
  "order_by": [["pageviews", "desc"]],
  "pagination": {
    "limit": 10
  }
}
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",
  "dimensions": ["event:page"],
  "order_by": [["pageviews", "desc"]],
  "pagination": {
    "limit": 10
  }
}
替换
<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'

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

可用指标

MetricTypeDescription
visitors
intUnique visitors
visits
intTotal sessions
pageviews
intPage views
bounce_rate
floatBounce rate (%)
visit_duration
intAvg duration (seconds)
views_per_visit
floatPages per session
conversion_rate
floatGoal conversion rate (requires goal to be configured)
events
intTotal 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

过滤运算符

OperatorDescription
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

日期范围选项

ValueDescription
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参考文档