hvac-marketing-skills/tools/integrations/plausible.md

Plausible Analytics

Privacy-focused, open-source web analytics with a simple API for stats queries without cookies or personal data collection.

Capabilities

Integration	Available	Notes
API	✓	Stats v2 Query, Sites Provisioning, Goals, Shared Links
MCP	-	Not available
CLI	✓	plausible.js
SDK	-	REST API only

Authentication

• Type: Bearer Token
• Header: Authorization: Bearer {api_key}
• Get key: https://plausible.io/settings > API Keys
• Note: Sites API requires Enterprise plan

Common Agent Operations

Stats Query (v2)

POST https://plausible.io/api/v2/query

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews", "bounce_rate", "visit_duration"],
  "date_range": "30d"
}

Top Pages

POST https://plausible.io/api/v2/query

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews"],
  "date_range": "30d",
  "dimensions": ["event:page"]
}

Traffic Sources

POST https://plausible.io/api/v2/query

{
  "site_id": "example.com",
  "metrics": ["visitors", "bounce_rate"],
  "date_range": "30d",
  "dimensions": ["visit:source"]
}

Time Series

POST https://plausible.io/api/v2/query

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews"],
  "date_range": "30d",
  "dimensions": ["time:day"]
}

Breakdown by Country

POST https://plausible.io/api/v2/query

{
  "site_id": "example.com",
  "metrics": ["visitors", "percentage"],
  "date_range": "30d",
  "dimensions": ["visit:country"]
}

Filtered Query (specific page)

POST https://plausible.io/api/v2/query

{
  "site_id": "example.com",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "30d",
  "filters": [["is", "event:page", ["/pricing"]]]
}

Realtime Visitors (v1)

GET https://plausible.io/api/v1/stats/realtime/visitors?site_id=example.com

List Sites

GET https://plausible.io/api/v1/sites

Key Metrics

Available Metrics

• visitors - Unique visitors
• visits - Total visits (sessions)
• pageviews - Total page views
• views_per_visit - Pages per session
• bounce_rate - Bounce rate percentage
• visit_duration - Average session duration (seconds)
• events - Total events
• conversion_rate - Goal conversion rate
• time_on_page - Average time on page
• scroll_depth - Average scroll depth
• percentage - Share of total

Available Dimensions

• event:page - Page path
• event:goal - Goal name
• visit:source - Traffic source
• visit:referrer - Referrer URL
• visit:channel - Traffic channel
• visit:utm_source, visit:utm_medium, visit:utm_campaign - UTM params
• visit:device - Device type
• visit:browser - Browser name
• visit:os - Operating system
• visit:country, visit:region, visit:city - Location
• visit:entry_page, visit:exit_page - Entry/exit pages
• time, time:day, time:week, time:month - Time periods

Parameters

Stats Query (v2)

• site_id (required) - Domain registered in Plausible
• metrics (required) - Array of metrics to return
• date_range (required) - Time period: "day", "7d", "30d", "month", "6mo", "12mo", "year", or custom ["2024-01-01", "2024-01-31"]
• dimensions - Array of dimensions to group by
• filters - Array of filter conditions: [operator, dimension, values]
• order_by - Array of sort specs: [[metric, "desc"]]
• pagination - { "limit": 100, "offset": 0 }

Filter Operators

• is / is_not - Exact match
• contains / contains_not - Substring match
• matches / matches_not - Wildcard match

When to Use

• Privacy-first web analytics without cookies
• Simple, lightweight traffic analysis
• UTM campaign performance tracking
• Goal and conversion tracking
• Geographic and device breakdown
• GDPR/CCPA-compliant analytics alternative to GA4

Rate Limits

• 600 requests/hour per API key
• All requests must be over HTTPS

Relevant Skills

• analytics-tracking
• content-strategy
• programmatic-seo
• page-cro
• utm-tracking