Plausible Analytics API

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

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

Get API Key

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 .

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

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'

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'

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'

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'

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'

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'

UTM Campaign Analysis

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'

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'

Site Provisioning 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

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'

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>"'

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>"'

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'

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'

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>"'

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'

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.

Available Dimensions

Event Dimensions

```
event:goal
```
- Custom goals
```
event:page
```
- Page path
```
event:hostname
```
- 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

Time Dimensions

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

Filter Operators

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

Complex Filters

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

Rate Limits

600 requests per hour per API key

API Reference

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

plausible

NPX Install

Tags

SKILL.md Content

Plausible Analytics API

When to Use

Prerequisites

Get API Key

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

Custom Date Range

Site Provisioning 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