> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/plausible/analytics/llms.txt
> Use this file to discover all available pages before exploring further.

# Breakdown Stats

> Break down your statistics by any property like pages, sources, countries, and more

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

<ParamField query="site_id" type="string" required>
  The domain of your site as configured in Plausible. Example: `example.com`
</ParamField>

<ParamField query="property" type="string" required>
  The dimension to break down the stats by.

  See the [Properties](#properties) section for all available dimensions.

  Note: `event:hostname` is currently not supported for breakdowns.
</ParamField>

<ParamField query="period" type="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.
</ParamField>

<ParamField query="date" type="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`.
</ParamField>

<ParamField query="metrics" type="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_rate`

  Note: Each metric can only be specified once.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of results to return per page. Must be between 1 and 1000.

  Default: `100`
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination. Use with `limit` to paginate through results.

  Default: `1`
</ParamField>

<ParamField query="filters" type="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
</ParamField>

<ParamField query="compare" type="string">
  Enable comparison with previous period. Set to `previous_period` to compare with the equivalent previous time period.
</ParamField>

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

<ResponseField name="results" type="array">
  Array of breakdown entries, ordered by the primary metric in descending order.

  <Expandable title="properties">
    <ResponseField name="[property]" type="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`
    </ResponseField>

    <ResponseField name="[metric]" type="number">
      Metric values as specified in the `metrics` parameter.

      One field for each requested metric (e.g., `visitors`, `pageviews`, `bounce_rate`).
    </ResponseField>

    <ResponseField name="comparison" type="object">
      Comparison data for the previous period (only present if `compare` parameter was used).

      <Expandable title="properties">
        <ResponseField name="[metric]" type="number">
          Metric values for the comparison period
        </ResponseField>

        <ResponseField name="change" type="object">
          Percentage change for each metric

          <Expandable title="properties">
            <ResponseField name="[metric]" type="number">
              Percentage change for this metric
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warning" type="string">
  Optional warning message (e.g., when imported stats are excluded)
</ResponseField>

## Examples

### Top Pages

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "results": [
      {
        "page": "/",
        "visitors": 5234,
        "pageviews": 8932
      },
      {
        "page": "/blog",
        "visitors": 3421,
        "pageviews": 4521
      },
      {
        "page": "/pricing",
        "visitors": 2134,
        "pageviews": 2876
      }
    ]
  }
  ```
</CodeGroup>

### Traffic Sources with Comparison

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "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
          }
        }
      }
    ]
  }
  ```
</CodeGroup>

### Countries Breakdown

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "results": [
      {
        "country": "US",
        "visitors": 12543,
        "visit_duration": 142
      },
      {
        "country": "GB",
        "visitors": 5234,
        "visit_duration": 156
      },
      {
        "country": "DE",
        "visitors": 3421,
        "visit_duration": 134
      }
    ]
  }
  ```
</CodeGroup>

### Custom Event Property

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "results": [
      {
        "author": "Jane Doe",
        "visitors": 1234,
        "events": 1876
      },
      {
        "author": "John Smith",
        "visitors": 987,
        "events": 1432
      }
    ]
  }
  ```
</CodeGroup>

### Pagination

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```
</CodeGroup>

## Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

### Common Errors

**400 Bad Request** - Missing property parameter

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

**400 Bad Request** - Invalid property

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "Please provide limit as a number between 1 and 1000."
}
```

**400 Bad Request** - Metric not supported in breakdown

```json theme={null}
{
  "error": "Metric `views_per_visit` is not supported in breakdown queries."
}
```