plausible

---
name: plausible
description: Plausible Analytics API for privacy-friendly stats. Use when user mentions
  "Plausible", "analytics", "page views", or website stats.
---

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name PLAUSIBLE_TOKEN` or `zero doctor check-connector --url https://plausible.io/api/v2/query --method POST`

## 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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X POST "https://plausible.io/api/v2/query" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -H "Content-Type: application/json" -d @/tmp/plausible_request.json
```

## Site Provisioning API

### List Sites

```bash
curl -s -H "Authorization: Bearer $PLAUSIBLE_TOKEN" "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
curl -s -X POST "https://plausible.io/api/v1/sites" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -H "Authorization: Bearer $PLAUSIBLE_TOKEN" "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
curl -s -X DELETE -H "Authorization: Bearer $PLAUSIBLE_TOKEN" "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
curl -s -X PUT "https://plausible.io/api/v1/sites/goals" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -X PUT "https://plausible.io/api/v1/sites/goals" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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
curl -s -H "Authorization: Bearer $PLAUSIBLE_TOKEN" "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
curl -s -X PUT "https://plausible.io/api/v1/sites/shared-links" -H "Authorization: Bearer $PLAUSIBLE_TOKEN" -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