Skip to main content

​
Introduction

The Plausible Analytics API provides programmatic access to your web analytics data. It consists of two main APIs:

Stats API

Query analytics data, metrics, and breakdowns for your sites

Sites API

Manage sites, goals, custom properties, and integrations

​
API Versions

Plausible offers multiple API versions:
  • v1 Stats API (/api/v1/stats) - Legacy stats endpoints with simple aggregations and breakdowns
  • v2 Query API (/api/v2/query) - Modern query API with advanced filtering and aggregations
  • v1 Sites API (/api/v1/sites) - Site provisioning and configuration (Enterprise Edition)

​
Base URL

All API requests should be made to: 
https://plausible.io/api
For self-hosted instances, replace plausible.io with your instance domain.

​
API Scopes

Plausible uses scope-based authorization. When creating an API key, you can assign one or more scopes:
Read-only access to stats endpoints. Default scope for all API keys.Allows:
  • Querying analytics data
  • Accessing breakdowns and timeseries
  • Reading realtime visitor counts
  • Accessing site metadata
Read-only access to site configuration and metadata.Allows:
  • Listing sites
  • Reading site details
  • Listing goals and custom properties
  • Viewing site guests
Full access to site provisioning and configuration.Allows:
  • All sites:read:* permissions
  • Creating and deleting sites
  • Managing goals and custom properties
  • Configuring shared links
  • Managing site guests
The scopes stats:read:* and sites:read:* are implicit and available to all API keys, even if not explicitly assigned.

​
Team-Scoped vs Legacy API Keys

Plausible supports two types of API keys: Modern API keys that are scoped to a specific team. These keys:
  • Only work with sites belonging to the associated team
  • Require the user to be a team member (not a guest)
  • Use team-based rate limiting
  • Are the only type available in the UI

​
Legacy Keys

Older API keys created before team-scoping was introduced:
  • Work across all teams the user belongs to
  • Work for sites where the user is a guest
  • Use user-based rate limiting
  • Cannot be created through the UI anymore
Legacy API keys are deprecated and maintained only for backwards compatibility. All new integrations should use team-scoped keys.

​
API Endpoints Structure

The API follows RESTful conventions: 
# Realtime visitors
GET /api/v1/stats/realtime/visitors?site_id=example.com

# Aggregate metrics
GET /api/v1/stats/aggregate?site_id=example.com&period=30d

# Breakdown by property
GET /api/v1/stats/breakdown?site_id=example.com&property=event:page

# Timeseries data
GET /api/v1/stats/timeseries?site_id=example.com&period=7d

​
Quick Start

1

Create an API key

Navigate to your account settings and create a new API key with the appropriate scopes for your use case.
2

Make your first request

Use the API key as a Bearer token in the Authorization header:
curl https://plausible.io/api/v1/stats/aggregate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d 'site_id=example.com' \
  -d 'period=30d' \
  -d 'metrics=visitors,pageviews'
3

Handle the response

All successful responses return JSON:
{
  "results": {
    "visitors": {"value": 12543},
    "pageviews": {"value": 18291}
  }
}

​
Feature Availability

Some API features require specific subscription plans:
FeatureRequired Plan
Stats APIBusiness plan or higher
Sites APIEnterprise plan
Custom PropertiesBusiness plan or higher
Funnels APIBusiness plan or higher
Revenue GoalsBusiness plan or higher
Shared LinksGrowth plan or higher
Site SegmentsGrowth plan or higher
If your account doesn’t have access to a required feature, API requests will return a 402 Payment Required error with details about upgrading your plan.

​
Response Formats

All API responses use JSON format with consistent structure:

​
Success Response

{
  "results": { /* endpoint-specific data */ },
  "meta": { /* optional pagination metadata */ },
  "warning": "Optional warning message"
}

​
Error Response

{
  "error": "Description of what went wrong"
}
HTTP status codes indicate the outcome:
  • 200 - Success
  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (missing or invalid API key)
  • 402 - Payment required (feature not available on your plan)
  • 404 - Not found (site or resource doesn’t exist)
  • 429 - Too many requests (rate limit exceeded)

​
Next Steps

Authentication

Learn how to authenticate your API requests

Stats API

Query analytics data and metrics

Rate Limits

Understand rate limiting and best practices

Sites API

Manage sites and configurations

Build docs developers (and LLMs) love

Get started for freeTalk to us