Agent skill

plausible

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

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/plausible

SKILL.md

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_TOKEN=your-api-key

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)

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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv PLAUSIBLE_TOKEN)" -H "Content-Type: application/json" -d @/tmp/plausible_request.json

Site Provisioning API

List Sites

bash
curl -s -H "Authorization: Bearer $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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 $(printenv 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

vm0-ai/vm0-skills

brave-search

Brave Search API for web search. Use when user says "search web", "Brave search", or asks to "find on web" without specifying Google.

50 8
Explore
vm0-ai/vm0-skills

supadata

Supadata API for YouTube/web data. Use when user mentions "Supadata", "YouTube data", "channel stats", or web scraping data.

50 8
Explore
vm0-ai/vm0-skills

roadmap-planning

Build and prioritize product roadmaps using scoring models like RICE, ICE, and value-effort matrices. Activate when creating a product roadmap, prioritizing features, sequencing initiatives, mapping dependencies, balancing team capacity, choosing between Now/Next/Later or quarterly planning, or communicating roadmap tradeoffs to executives and stakeholders.

50 8
Explore
vm0-ai/vm0-skills

qdrant

Qdrant API for vector search. Use when user mentions "Qdrant", "vector database", "semantic search", or embeddings storage.

50 8
Explore
vm0-ai/vm0-skills

calendly

Calendly scheduling API. Use when user mentions "Calendly", "calendly.com", "schedule a meeting", "booking link", "event types", or asks about interview scheduling.

50 8
Explore
vm0-ai/vm0-skills

stripe

Stripe API for payments. Use when user mentions "Stripe", "payment", "subscription", "billing", "invoice", or asks about payment processing.

50 8
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results