plausible

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

```bash

export PLAUSIBLE_API_KEY=your-api-key

export PLAUSIBLE_SITE_ID=example.com

```

Get API Key

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 .

> ```

Basic Query - Total Visitors

Write to /tmp/plausible_request.json:

```json

{

"site_id": "",

"metrics": ["visitors", "pageviews"],

"date_range": "7d"

}

```

Replace 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": "",

"metrics": ["visitors", "pageviews", "bounce_rate"],

"date_range": "30d",

"dimensions": ["visit:source"]

}

```

Replace 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": "",

"metrics": ["visitors", "pageviews"],

"date_range": "7d",

"dimensions": ["event:page"],

"order_by": [["pageviews", "desc"]],

"pagination": {

"limit": 10

}

}

```

Replace 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": "",

"metrics": ["visitors"],

"date_range": "30d",

"dimensions": ["visit:country_name", "visit:city_name"]

}

```

Replace 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": "",

"metrics": ["visitors"],

"date_range": "7d",

"dimensions": ["visit:device"]

}

```

Replace 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": "",

"metrics": ["visitors", "pageviews"],

"date_range": "30d",

"dimensions": ["time:day"]

}

```

Replace 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": "",

"metrics": ["visitors", "pageviews"],

"date_range": "7d",

"filters": [["contains", "event:page", ["/blog"]]]

}

```

Replace 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": "",

"metrics": ["visitors", "conversion_rate"],

"date_range": "30d",

"dimensions": ["visit:utm_source", "visit:utm_campaign"]

}

```

Replace 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": "",

"metrics": ["visitors", "pageviews"],

"date_range": ["2024-01-01", "2024-01-31"]

}

```

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

```

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

```

Delete Site

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

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

```

Create Goal

Write to /tmp/plausible_request.json:

```json

{

"site_id": "",

"goal_type": "event",

"event_name": "Signup"

}

```

Replace 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": "",

"goal_type": "page",

"page_path": "/thank-you"

}

```

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

```

Create Shared Link

Write to /tmp/plausible_request.json:

```json

{

"site_id": "",

"name": "Public Dashboard"

}

```

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

```

| 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.

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

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

]]

```

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

• 600 requests per hour per API key

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