Breakdown Stats

The breakdown endpoint allows you to break down your statistics by a specific dimension (property). Use this to see which pages get the most traffic, which countries your visitors come from, which sources drive the most conversions, and more.

Endpoint

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

Authentication

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

Authorization: Bearer YOUR_API_KEY

Query Parameters

string

required

The domain of your site as configured in Plausible. Example: example.com

string

required

The dimension to break down the stats by.See the Properties section for all available dimensions.Note: event:hostname is currently not supported for breakdowns.

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.

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.

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
conversion_rate - Goal conversion rate
time_on_page - Average time on page in seconds (only for event:page breakdown)

Example: visitors,pageviews,bounce_rateNote: Each metric can only be specified once.

integer

Maximum number of results to return per page. Must be between 1 and 1000.Default: 100

integer

Page number for pagination. Use with limit to paginate through results.Default: 1

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

string

Enable comparison with previous period. Set to previous_period to compare with the equivalent previous time period.

Properties

Available dimensions for breaking down stats:

Event Properties

event:page - Page path
event:name - Custom event name
event:goal - Goal name (pageview or custom event goal)
event:props:* - Custom event properties (e.g., event:props:author, event:props:button_id)

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 in breakdown queries:

time_on_page - Only supported for event:page breakdown
views_per_visit - Not supported in breakdown queries
conversion_rate - When breaking down by dimensions other than event:goal or custom properties, this represents the percentage of total visitors in that segment
Session metrics (visits, bounce_rate, visit_duration) - Cannot be used when breaking down by event:name, event:goal, or custom event properties (event:props:*)

Response

array

Array of breakdown entries, ordered by the primary metric in descending order.

Show properties

string | number

The dimension value (property name varies based on the property parameter).For example:

When property=event:page, the field will be page
When property=visit:country, the field will be country
When property=event:props:author, the field will be author

number

Metric values as specified in the metrics parameter.One field for each requested metric (e.g., visitors, pageviews, bounce_rate).

object

Comparison data for the previous period (only present if compare parameter was used).

Show properties

number

Metric values for the comparison period

object

Percentage change for each metric

Show properties

number

Percentage change for this metric

string

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

Examples

Top Pages

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

const response = await fetch(
  'https://plausible.io/api/v1/stats/breakdown?site_id=example.com&period=7d&property=event:page&metrics=visitors,pageviews&limit=10',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();

import requests

response = requests.get(
    'https://plausible.io/api/v1/stats/breakdown',
    params={
        'site_id': 'example.com',
        'period': '7d',
        'property': 'event:page',
        'metrics': 'visitors,pageviews',
        'limit': 10
    },
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

{
  "results": [
    {
      "page": "/",
      "visitors": 5234,
      "pageviews": 8932
    },
    {
      "page": "/blog",
      "visitors": 3421,
      "pageviews": 4521
    },
    {
      "page": "/pricing",
      "visitors": 2134,
      "pageviews": 2876
    }
  ]
}

Traffic Sources with Comparison

curl "https://plausible.io/api/v1/stats/breakdown?site_id=example.com&period=month&property=visit:source&metrics=visitors,visits,bounce_rate&compare=previous_period" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": [
    {
      "source": "Google",
      "visitors": 4532,
      "visits": 5234,
      "bounce_rate": 58.3,
      "comparison": {
        "visitors": 4123,
        "visits": 4892,
        "bounce_rate": 61.2,
        "change": {
          "visitors": 10,
          "visits": 7,
          "bounce_rate": -5
        }
      }
    },
    {
      "source": "Twitter",
      "visitors": 2341,
      "visits": 2567,
      "bounce_rate": 45.2,
      "comparison": {
        "visitors": 1987,
        "visits": 2134,
        "bounce_rate": 47.8,
        "change": {
          "visitors": 18,
          "visits": 20,
          "bounce_rate": -5
        }
      }
    }
  ]
}

Countries Breakdown

curl "https://plausible.io/api/v1/stats/breakdown?site_id=example.com&period=30d&property=visit:country&metrics=visitors,visit_duration&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": [
    {
      "country": "US",
      "visitors": 12543,
      "visit_duration": 142
    },
    {
      "country": "GB",
      "visitors": 5234,
      "visit_duration": 156
    },
    {
      "country": "DE",
      "visitors": 3421,
      "visit_duration": 134
    }
  ]
}

Custom Event Property

curl "https://plausible.io/api/v1/stats/breakdown?site_id=example.com&period=7d&property=event:props:author&metrics=visitors,events&filters=event:name==Article%20View" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": [
    {
      "author": "Jane Doe",
      "visitors": 1234,
      "events": 1876
    },
    {
      "author": "John Smith",
      "visitors": 987,
      "events": 1432
    }
  ]
}

Pagination

# Get second page of results
curl "https://plausible.io/api/v1/stats/breakdown?site_id=example.com&period=30d&property=event:page&metrics=visitors&limit=50&page=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

string

Error message describing what went wrong

Common Errors

400 Bad Request - Missing property parameter

{
  "error": "The `property` parameter is required. Please provide at least one property to show a breakdown by."
}

400 Bad Request - Invalid property

{
  "error": "Invalid property 'invalid_prop'. Please provide a valid property for the breakdown endpoint: https://plausible.io/docs/stats-api#properties"
}

400 Bad Request - Unsupported property

{
  "error": "Property 'event:hostname' is currently not supported for breakdowns. Please provide a valid property for the breakdown endpoint: https://plausible.io/docs/stats-api#properties"
}

400 Bad Request - Invalid limit

{
  "error": "Please provide limit as a number between 1 and 1000."
}

400 Bad Request - Metric not supported in breakdown

{
  "error": "Metric `views_per_visit` is not supported in breakdown queries."
}

Overview

Stats API

Sites API

Events API

Goals API

Endpoint

Authentication

Query Parameters

Properties

Event Properties

Visit (Session) Properties

Metric Constraints

Response

Examples

Top Pages

Traffic Sources with Comparison

Countries Breakdown

Custom Event Property

Error Responses

Common Errors

​Endpoint

​Authentication

​Query Parameters

​Properties

​Event Properties

​Visit (Session) Properties

​Metric Constraints

​Response

​Examples

​Top Pages

​Traffic Sources with Comparison

​Countries Breakdown

​Custom Event Property

​Pagination

​Error Responses

​Common Errors

Endpoint

Authentication

Query Parameters

Properties

Event Properties

Visit (Session) Properties

Metric Constraints

Response

Examples

Top Pages

Traffic Sources with Comparison

Countries Breakdown

Custom Event Property

Pagination

Error Responses

Common Errors