playbooks

home / skills / vm0-ai / vm0-skills / plausible

plausible skill

/plausible

This skill helps you query Plausible analytics and manage sites to monitor visitors, pageviews, sources, and conversions efficiently.

npx playbooks add skill vm0-ai/vm0-skills --skill plausible

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
10.7 KB
---
name: plausible
description: Plausible Analytics API for querying website statistics and managing sites. Use this skill to get visitor counts, pageviews, traffic sources, and manage analytics sites.
vm0_secrets:
  - PLAUSIBLE_API_KEY
vm0_vars:
  - PLAUSIBLE_SITE_ID
---

# 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

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

Overview

This skill provides a shell-focused interface to the Plausible Analytics API for querying website statistics and managing sites. It helps retrieve visitors, pageviews, traffic sources, geographic and device breakdowns, and manage sites, goals, and shared links. Use it to automate analytics reporting and site provisioning with curl-based commands.

How this skill works

Commands create JSON requests written to a temporary file and call Plausible endpoints with curl using an API key stored in environment variables. The skill supports the Stats API (v2) for queries with metrics, dimensions, filters, date ranges and pagination, and the Sites API (v1) for listing, creating, deleting sites and managing goals and shared links. Use bash -c when piping to avoid environment variable clearing with pipes.

When to use it

  • Run quick visitor, pageview, or time series queries for a site from a CI job or shell script.
  • Generate top pages, geographic or device breakdowns for a reporting dashboard.
  • Filter analytics by page path, UTM campaign, or custom dimensions for campaign analysis.
  • Provision new sites, create goals, or create shared dashboard links programmatically.
  • Automate periodic exports within Plausible rate limits (600 requests/hour).

Best practices

  • Store PLAUSIBLE_API_KEY and PLAUSIBLE_SITE_ID in environment variables and never commit them to source control.
  • Write JSON payloads to a temporary file and use bash -c 'curl ...' when piping to jq to preserve env variables.
  • Limit pagination and use date ranges to reduce payload size and stay within rate limits.
  • Create goals before querying conversion_rate metrics to ensure meaningful results.
  • Use dimensions and filters to narrow queries and reduce post-processing work.

Example use cases

  • Daily CI job that posts yesterday's visitors and top 10 pages to a Slack channel.
  • Marketing report breaking down visitors by UTM source and campaign for the last 30 days.
  • Geo heatmap generation using visit:country_name and visit:city_name for the past month.
  • Automated site onboarding that creates a new site, configures timezone, and creates a signup goal.
  • Ad-hoc debugging: filter events by page path to verify analytics tagging on a /blog section.

FAQ

How do I get an API key?

Log in to plausible.io, go to Account Settings → API Keys, create a new key (Stats API or Sites API) and save it.

Why use bash -c with curl when piping?

Some shells clear environment variables when a command with a pipe is executed. Wrapping curl in bash -c preserves PLAUSIBLE_API_KEY for the request.