plausible

What this skill does

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