Aggregate Stats

Retrieve aggregated statistics for your site over a specified time period

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-01

For 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_rate

Note: 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.

Show properties

[metric_name] · object

Show properties

value · number

The metric value for the requested period

comparison_value · number

The metric value for the comparison period (only present if compare parameter was used)

change · number

Percentage change between periods (only present if compare parameter was used)

warning · string

Optional warning message (e.g., when imported stats are excluded)

Examples

Basic Request

cURL

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

Response

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

With Filters and Comparison

cURL

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"

Response

{
  "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

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"

Response

{
  "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"
}