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

# 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

<ParamField query="site_id" type="string" required>
  The domain of your site as configured in Plausible. Example: `example.com`
</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
  * `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.
</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

  See the [Properties](#properties) section for available dimensions.
</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 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

<ResponseField name="results" type="object">
  Object containing the requested metrics with their values.

  <Expandable title="properties">
    <ResponseField name="[metric_name]" type="object">
      <Expandable title="properties">
        <ResponseField name="value" type="number">
          The metric value for the requested period
        </ResponseField>

        <ResponseField name="comparison_value" type="number">
          The metric value for the comparison period (only present if `compare` parameter was used)
        </ResponseField>

        <ResponseField name="change" type="number">
          Percentage change between periods (only present if `compare` parameter was used)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

## Examples

### Basic Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://plausible.io/api/v1/stats/aggregate?site_id=example.com&period=7d&metrics=visitors,pageviews" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://plausible.io/api/v1/stats/aggregate?site_id=example.com&period=7d&metrics=visitors,pageviews',
    {
      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/aggregate',
      params={
          'site_id': 'example.com',
          'period': '7d',
          'metrics': 'visitors,pageviews'
      },
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )
  data = response.json()
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "results": {
      "visitors": {
        "value": 12543
      },
      "pageviews": {
        "value": 28392
      }
    }
  }
  ```
</CodeGroup>

### With Filters and Comparison

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

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

### Custom Date Range

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

<CodeGroup>
  ```json Response theme={null}
  {
    "results": {
      "visitors": {
        "value": 45678
      },
      "events": {
        "value": 123456
      }
    }
  }
  ```
</CodeGroup>

## Error Responses

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

### Common Errors

**400 Bad Request** - Invalid parameters

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

```json theme={null}
{
  "error": "Metric `conversion_rate` can only be queried in a goal breakdown or with a goal filter"
}
```

**401 Unauthorized** - Invalid or missing API key

```json theme={null}
{
  "error": "Invalid API key"
}
```