Skip to main content
The aggregate endpoint allows you to retrieve aggregated statistics for your site. Use this endpoint to get high-level metrics like total visitors, pageviews, bounce rate, and visit duration over a specified time period.

​
Endpoint

GET https://plausible.io/api/v1/stats/aggregate

​
Authentication

All requests must include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Query Parameters

​
site_id
string
required
The domain of your site as configured in Plausible. Example: example.com
​
period
string
The time period for the query. Valid values:
  • day - Current day
  • 7d - Last 7 days
  • 30d - Last 30 days
  • month - Current month
  • 6mo - Last 6 months
  • 12mo - Last 12 months
  • custom - Custom date range (requires date parameter)
Defaults to 30d if not specified.
​
date
string
Date or date range in ISO-8601 format.For single date periods: 2024-01-01For custom periods: 2024-01-01,2024-01-31 (comma-separated start and end dates)Required when period=custom.
​
metrics
string
Comma-separated list of metrics to retrieve. Defaults to visitors if not specified.Available metrics:
  • visitors - Unique visitors
  • visits - Total visits (sessions)
  • pageviews - Total pageviews
  • events - Total events
  • bounce_rate - Bounce rate percentage
  • visit_duration - Average visit duration in seconds
  • views_per_visit - Average pageviews per visit
  • conversion_rate - Goal conversion rate (requires goal filter)
  • time_on_page - Average time on page in seconds (requires page filter)
Example: visitors,pageviews,bounce_rateNote: Each metric can only be specified once. Metrics cannot be queried multiple times.
​
filters
string
Filter the data by specific dimensions. Format: dimension==value for equality or dimension!=value for negation.Multiple filters can be combined with semicolons (;).Multiple values for the same dimension can be combined with pipes (|).Wildcard matching is supported using asterisks (*).Examples:
  • event:page==/blog - Filter to a specific page
  • visit:country==US - Filter to United States traffic
  • visit:source==Google|Twitter - Filter to Google or Twitter traffic
  • event:page==/blog** - Wildcard match for blog pages
  • visit:country!=US;visit:source==Google - Combine multiple filters
See the Properties section for available dimensions.
​
compare
string
Enable comparison with previous period. Set to previous_period to compare with the equivalent previous time period.

​
Properties

Available dimensions for filtering:

​
Event Properties

  • event:page - Page path
  • event:name - Custom event name
  • event:goal - Goal name (pageview or custom event goal)
  • event:hostname - Hostname (not supported for breakdowns)
  • event:props:* - Custom event properties (e.g., event:props:author)

​
Visit (Session) Properties

  • visit:source - Traffic source
  • visit:channel - Traffic channel
  • visit:country - Country code (ISO 3166-1 alpha-2)
  • visit:region - Region code
  • visit:city - City name
  • visit:entry_page - Entry page path
  • visit:exit_page - Exit page path
  • visit:referrer - Referrer URL
  • visit:utm_medium - UTM medium
  • visit:utm_source - UTM source
  • visit:utm_campaign - UTM campaign
  • visit:utm_content - UTM content
  • visit:utm_term - UTM term
  • visit:device - Device type (Desktop, Mobile, Tablet)
  • visit:os - Operating system
  • visit:os_version - Operating system version
  • visit:browser - Browser name
  • visit:browser_version - Browser version

​
Metric Constraints

Certain metrics have specific requirements:
  • conversion_rate - Can only be queried with a goal filter (event:goal==)
  • time_on_page - Can only be queried with a page filter or in a page breakdown
  • Session metrics (visits, bounce_rate, visit_duration, views_per_visit) - Cannot be queried when filtering by event:name, event:goal, or custom event properties

​
Response

​
results
object
Object containing the requested metrics with their values.
​
warning
string
Optional warning message (e.g., when imported stats are excluded)

​
Examples

​
Basic Request

curl "https://plausible.io/api/v1/stats/aggregate?site_id=example.com&period=7d&metrics=visitors,pageviews" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": {
    "visitors": {
      "value": 12543
    },
    "pageviews": {
      "value": 28392
    }
  }
}

​
With Filters and Comparison

curl "https://plausible.io/api/v1/stats/aggregate?site_id=example.com&period=30d&metrics=visitors,bounce_rate,visit_duration&filters=visit:country==US&compare=previous_period" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": {
    "visitors": {
      "value": 8234,
      "comparison_value": 7891,
      "change": 4
    },
    "bounce_rate": {
      "value": 62.5,
      "comparison_value": 65.2,
      "change": -4
    },
    "visit_duration": {
      "value": 145,
      "comparison_value": 132,
      "change": 10
    }
  }
}

​
Custom Date Range

curl "https://plausible.io/api/v1/stats/aggregate?site_id=example.com&period=custom&date=2024-01-01,2024-01-31&metrics=visitors,events" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": {
    "visitors": {
      "value": 45678
    },
    "events": {
      "value": 123456
    }
  }
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Errors

400 Bad Request - Invalid parameters 
{
  "error": "The metric `invalid_metric` is not recognized. Find valid metrics from the documentation: https://plausible.io/docs/stats-api#metrics"
}
400 Bad Request - Metric validation failed 
{
  "error": "Metric `conversion_rate` can only be queried in a goal breakdown or with a goal filter"
}
401 Unauthorized - Invalid or missing API key 
{
  "error": "Invalid API key"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us