Plausible Analytics

https://plausible.io/docs
Admin
Plausible Analytics is an easy-to-use, open-source, lightweight, and privacy-friendly alternative to...
Tokens:143,044
Snippets:1,242
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example: head imported_browsers_20230209_20240123.csv

Source: https://plausible.io/docs/csv-import

Sample CSV content for the imported_browsers table, showing the expected columns and data types. The example includes a header row and several data rows with quoted fields.

```bash
$ head imported_browsers_20230209_20240123.csv  
"date","browser","browser_version","visitors","visits","visit_duration","bounces","pageviews"  
"2023-02-09","Safari","16.3",5,6,512,2,10  
"2023-02-09","Chrome","109.0",54,60,6627,40,128  
"2023-02-09","Chrome","108.0",2,3,47,2,6  
"2023-02-09","Chrome","47.0",1,1,82,0,2  
"2023-02-09","Safari","16.2",2,2,21,1,3  
"2023-02-09","Microsoft Edge","111.0",1,1,987,0,3  
"2023-02-09","Chrome","110.0",11,14,5145,6,37  
"2023-02-09","Firefox","109.0",24,26,5284,16,51  
"2023-02-09","Firefox","110.0",4,4,690,1,8  
```

--------------------------------

### Plausible snippet example

Source: https://plausible.io/docs/proxy/guides/apache

Example Plausible snippet from the Site Installation area. Replace the script location with your personalized URL (e.g., https://plausible.io/js/pa-XXXXX.js) before using.

```html
<script async src="https://plausible.io/js/pa-XXXXX.js"></script>  
<script>  
  window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};  
  plausible.init()  
</script>  

```

--------------------------------

### Example: head imported_entry_pages_20230209_20240123.csv

Source: https://plausible.io/docs/csv-import

Sample CSV content for the imported_entry_pages table, showing the expected columns and data types. The example includes a header row and several data rows with quoted fields.

```bash
$ head imported_entry_pages_20230209_20240123.csv  
"date","entry_page","visitors","entrances","visit_duration","bounces","pageviews"  
"2023-02-09","/docs/proxy/guides/nginx",1,1,922,0,7  
"2023-02-09","/docs/goal-conversions",3,3,1072,1,6  
"2023-02-09","/docs/webflow-integration",2,2,224,1,11  
"2023-02-09","/docs/google-search-console-integration",7,7,114,6,8  
"2023-02-09","/docs/proxy/introduction",3,3,0,3,3  
"2023-02-09","/docs/script-extensions",4,4,393,2,7  
"2023-02-09","/docs/troubleshoot-integration",3,3,2372,1,10  
"2023-02-09","/docs/outbound-link-click-tracking",1,1,0,1,1  
"2023-02-09","/docs",28,29,3573,13,64  
```

--------------------------------

### Example list response with pagination metadata

Source: https://plausible.io/docs/sites-api

Example response from a list endpoint showing pagination metadata under `meta`. The `after` and `before` fields contain cursor values for navigating pages; `null` indicates no more pages in that direction.

```json
{
  "sites": [...],
  "meta": {
    "after": "Z2xc...",
    "before": null,
    "limit": 100
  }
}

```

--------------------------------

### Example pageview call with custom parameters article and page

Source: https://plausible.io/docs/custom-query-params

Example of the last line of the trigger script using the custom parameters 'article' and 'page'. This will report the page path as blog/index.php/some_article/11 for a URL like yoursite.com/blog/index.php?article=some_article&page=11.

```javascript
plausible('pageview', { url: prepareUrl(["article", "page"]) + window.location.search });  

```

--------------------------------

### Setup block for custom pixel (required)

Source: https://plausible.io/docs/shopify-integration

Required setup block for the custom pixel. Place at the top of the code block and replace 'yourdomain.com' with your Plausible site name. This block does not track anything by itself but is required for all other snippets to work.

```javascript
const DATA_DOMAIN = 'yourdomain.com';  
  
const script = document.createElement('script');  
script.defer = true;  
script.dataset.domain = DATA_DOMAIN;  
script.dataset.api = 'https://plausible.io/api/event';  
script.src = 'https://plausible.io/js/script.manual.revenue.js';  
document.head.appendChild(script);  
  
window.plausible = window.plausible || function() {  
  (window.plausible.q = window.plausible.q || []).push(arguments)  
}  

```

--------------------------------

### imported_operating_systems CSV example

Source: https://plausible.io/docs/csv-import

Shows the expected CSV format for the imported_operating_systems table. The operating_system and operating_system_version columns can be empty strings when the value is unknown.

```bash
$ head imported_operating_systems_20230209_20240123.csv  
"date","operating_system","operating_system_version","visitors","visits","visit_duration","bounces","pageviews"  
"2023-02-09","Tizen","3.0",1,1,82,0,2  
"2023-02-09","Android","11",1,1,19,0,2  
"2023-02-09","iOS","16.2",1,1,0,1,1  
"2023-02-09","Windows","7",1,1,0,1,1  
"2023-02-09","Mac","10.14",1,1,19,0,2  
"2023-02-09","iOS","16.3",1,1,0,1,1  
"2023-02-09","","",1,1,8,0,24  
"2023-02-09","Android","12",2,2,0,2,2  
"2023-02-09","iOS","16.1",5,6,39,5,8  

```

--------------------------------

### GET /api/v1/stats/timeseries

Source: https://plausible.io/docs/stats-api-v1

Example of using the timeseries endpoint to get monthly traffic from Google.

```APIDOC
## GET /api/v1/stats/timeseries

### Description
Retrieves time series data for a site, such as monthly traffic from a specific source.

### Method
GET

### Endpoint
/api/v1/stats/timeseries

### Parameters
#### Query Parameters
- **site_id** (string) - Required - The site identifier.
- **period** (string) - Required - The time period (e.g., `6mo`).
- **filters** (string) - Optional - Filter expression (e.g., `visit:source==Google`).

### Request Example
```
curl "https://plausible.io/api/v1/stats/timeseries?site_id=$SITE_ID&period=6mo&filters=visit:source%3D%3DGoogle" \
  -H "Authorization: Bearer ${TOKEN}"
```

### Response
#### Success Response (200)
- **results** (array) - List of time series data points.
  - **date** (string) - The date in YYYY-MM-DD format.
  - **visitors** (integer) - Number of visitors.

#### Response Example
```
{
  "results": [
    {
        "date": "2020-09-01",
        "visitors": 2962
    },
    {
        "date": "2020-10-01",
        "visitors": 4974
    },
    {
        "date": "2020-11-01",
        "visitors": 5119
    },
    {
        "date": "2020-12-01",
        "visitors": 5397
    },
    {
        "date": "2021-01-01",
        "visitors": 7167
    },
    {
        "date": "2021-02-01",
        "visitors": 5802
    }
  ]
}
```
```

--------------------------------

### GET /api/v1/stats/aggregate

Source: https://plausible.io/docs/stats-api-v1

Example of using the aggregate endpoint to get the number of visitors to a specific page.

```APIDOC
## GET /api/v1/stats/aggregate

### Description
Retrieves aggregate statistics for a site, such as the number of visitors to a specific page.

### Method
GET

### Endpoint
/api/v1/stats/aggregate

### Parameters
#### Query Parameters
- **site_id** (string) - Required - The site identifier.
- **period** (string) - Required - The time period (e.g., `6mo`).
- **filters** (string) - Optional - Filter expression (e.g., `event:page==/order/confirmation`).

### Request Example
```
curl "https://plausible.io/api/v1/stats/aggregate?site_id=$SITE_ID&period=6mo&filters=event:page%3D%3D%2Forder%2Fconfirmation" \
  -H "Authorization: Bearer ${TOKEN}"
```

### Response
#### Success Response (200)
- **results** (object) - Contains the aggregate metrics.
  - **visitors** (object) - Contains the visitor count.
    - **value** (integer) - The number of visitors.

#### Response Example
```
{
  "results": {
    "visitors": {
        "value": 1480
    }
  }
}
```
```

--------------------------------

### plausible.init()

Source: https://plausible.io/docs/script-extensions

Configuration options for the plausible.init() function to customize tracking behavior.

```APIDOC
## plausible.init()

### Description
Initializes the Plausible analytics script with configurable options to enhance tracking behavior.

### Method
Function call

### Endpoint
`plausible.init(options)`

### Parameters
#### Options
- **endpoint** (string) - Optional - Default: `"https://plausible.io/api/event"` - Allows proxying requests
- **hashBasedRouting** (boolean) - Optional - Default: `false` - Track page paths that use a `#` in the URL (hash-based routing)
- **fileDownloads** (boolean or `{ fileExtensions }`) - Optional - Default: `false` - Automatically track file downloads
- **outboundLinks** (boolean) - Optional - Default: `false` - Track clicks on outbound links
- **customProperties** (object or `function(eventName)`) - Optional - Default: `{}` - Add custom props globally
- **formSubmissions** (boolean) - Optional - Default: `false` - Track form submissions
- **captureOnLocalhost** (boolean) - Optional - Default: `false` - Enables tracking on localhost for dev environments
- **autoCapturePageviews** (boolean) - Optional - Default: `true` - Automatically track pageviews
- **logging** (boolean) - Optional - Default: `true` - Enable/disable logging done by script
- **transformRequest** (function(payload)) - Optional - Modify or filter events before sending (e.g. for custom locations)

### Example
```javascript
plausible.init({ autoCapturePageviews: false });
```
```

--------------------------------

### GET /api/v1/stats/breakdown

Source: https://plausible.io/docs/stats-api-v1

Example of using the breakdown endpoint to get top pages and breakdown of custom event properties.

```APIDOC
## GET /api/v1/stats/breakdown

### Description
Retrieves a breakdown of statistics grouped by a specified property, such as `event:page` for top pages or `event:props:method` for custom event properties.

### Method
GET

### Endpoint
/api/v1/stats/breakdown

### Parameters
#### Query Parameters
- **site_id** (string) - Required - The site identifier.
- **period** (string) - Required - The time period (e.g., `6mo`).
- **property** (string) - Required - The property to group by (e.g., `event:page`).
- **limit** (integer) - Optional - The maximum number of results to return.
- **filters** (string) - Optional - Filter expression (e.g., `event:goal==Download`).

### Request Example
```
curl "https://plausible.io/api/v1/stats/breakdown?site_id=$SITE_ID&period=6mo&property=event:page&limit=5" \
  -H "Authorization: Bearer ${TOKEN}"
```

### Response
#### Success Response (200)
- **results** (array) - List of breakdown items.
  - **page** (string) - The page path (when property is `event:page`).
  - **visitors** (integer) - Number of visitors.
  - **method** (string) - The custom property value (when property is `event:props:method`).

#### Response Example
```
{
  "results": [
    {
      "page": "/",
      "visitors": 94298
    },
    {
      "page": "/blog/open-source-licenses",
      "visitors": 18803
    },
    {
      "page": "/plausible.io",
      "visitors": 20485
    },
    {
      "page": "/self-hosted-web-analytics",
      "visitors": 22236
    },
    {
      "page": "/sites",
      "visitors": 32386
    }
  ]
}
```
```

--------------------------------

### GET /api/v1/stats/breakdown - curl request and response

Source: https://plausible.io/docs/stats-api-v1

Example request to the Plausible Stats API breakdown endpoint, fetching top sources for the last 6 months with visitors and bounce rate, limited to 5 results. The response shows the JSON structure with results array containing bounce_rate, source, and visitors fields.

```bash
curl "https://plausible.io/api/v1/stats/breakdown?site_id=$SITE_ID&period=6mo&property=visit:source&metrics=visitors,bounce_rate&limit=5" \
  -H "Authorization: Bearer ${TOKEN}"
```

```json
{  
  "results": [  
    {  
        "bounce_rate": 49.0,  
        "source": "(Direct / None)",  
        "visitors": 94932  
    },  
    {  
        "bounce_rate": 75.0,  
        "source": "Hacker News",  
        "visitors": 22540  
    },  
    {  
        "bounce_rate": 58.0,  
        "source": "Google",  
        "visitors": 16909  
    },  
    {  
        "bounce_rate": 62.0,  
        "source": "Twitter",  
        "visitors": 7477  
    },  
    {  
        "bounce_rate": 56.0,  
        "source": "indiehackers.com",  
        "visitors": 4518  
    }  
  ]  
}
```

--------------------------------

### Enable Apache proxy modules

Source: https://plausible.io/docs/proxy/guides/apache

Enable the Apache modules required for proxying Plausible: proxy, proxy_http, and ssl. Run these commands as root or with sudo.

```bash
sudo a2enmod proxy  
sudo a2enmod proxy_http  
sudo a2enmod ssl  

```

--------------------------------

### GET /api/v1/sites

Source: https://plausible.io/docs/sites-api

Gets a list of existing sites your Plausible account can access. Supports pagination and team scoping.

```APIDOC
## GET /api/v1/sites

### Description
Gets a list of existing sites your Plausible account can access.

### Method
GET

### Endpoint
/api/v1/sites

### Parameters
#### Query Parameters
- **after** (string) - Optional - Pagination cursor. See Pagination.
- **before** (string) - Optional - Pagination cursor. See Pagination.
- **limit** (integer) - Optional - Pagination limit. Defaults to 100. See Pagination.
- **team_id** (string) - Optional - ID of the team to scope the list of sites by. All sites including the ones accessible via guest membership are listed when no ID provided.

### Request Example
```
curl -X GET https://plausible.io/api/v1/sites \
  -H "Authorization: Bearer ${TOKEN}"
```

### Response
#### Success Response (200)
- **sites** (array) - List of sites.
  - **domain** (string) - Domain of the site.
  - **timezone** (string) - Timezone of the site.
- **meta** (object) - Pagination metadata.
  - **after** (string|null) - Pagination cursor.
  - **before** (string|null) - Pagination cursor.
  - **limit** (integer) - Pagination limit.

#### Response Example
```
{
    "sites": [
        {
            "domain": "test-domain1.com",
            "timezone": "Europe/London"
        },
        {
            "domain": "test-domain2.com",
            "timezone": "Europe/London"
        },
        {
            "domain": "test-domain3.com",
            "timezone": "Europe/London"
        }
    ],
    "meta": {
        "after": null,
        "before": null,
        "limit": 100
    }
}
```
```

--------------------------------

### GET /api/v1/sites/teams

Source: https://plausible.io/docs/sites-api

Gets a list of teams your Plausible account can access. The api_available attribute determines if the API is available for a given team.

```APIDOC
## GET /api/v1/sites/teams

### Description
Gets a list of teams your Plausible account can access. The `api_available` attribute determines if the API is available for a given team.

### Method
GET

### Endpoint
/api/v1/sites/teams

### Parameters
#### Query Parameters
- **after** (string) - Optional - Pagination cursor. See Pagination.
- **before** (string) - Optional - Pagination cursor. See Pagination.
- **limit** (integer) - Optional - Pagination limit. Defaults to 100. See Pagination.

### Request Example
```
curl -X GET https://plausible.io/api/v1/sites/teams \
  -H "Authorization: Bearer ${TOKEN}"
```

### Response
#### Success Response (200)
- **teams** (array) - List of teams.
  - **id** (string) - Team ID.
  - **name** (string) - Team name.
  - **api_available** (boolean) - Whether the API is available for the team.
- **meta** (object) - Pagination metadata.
  - **after** (string|null) - Pagination cursor.
  - **before** (string|null) - Pagination cursor.
  - **limit** (integer) - Pagination limit.

#### Response Example
```
{
    "teams": [
        {
            "id": "4d3dae3b-2a44-4aaa-baac-6bb55234a435",
            "name": "My Personal Sites",
            "api_available": false
        },
        {
            "id": "ef828bca-8a1b-49f6-b829-dee1c9f7d628",
            "name": "Some Team",
            "api_available": true
        },
        {
            "id": "59e4d5b3-fc1c-464d-95f2-dbe6983396be",
            "name": "Another Team",
            "api_available": true
        }
    ],
    "meta": {
        "after": null,
        "before": null,
        "limit": 100
    }
}
```
```

--------------------------------

### Example CSV for imported_visitors

Source: https://plausible.io/docs/csv-import

Shows the expected CSV format for the imported_visitors table, with columns date, visitors, pageviews, bounces, visits, and visit_duration. The header row uses quoted field names and the data rows use ISO dates and integer counts.

```bash
$ head imported_visitors_20230209_20240123.csv  
"date","visitors","pageviews","bounces","visits","visit_duration"  
"2023-02-09",119,304,77,134,21070  
"2023-02-10",166,325,117,180,21467  
"2023-02-11",117,233,92,128,16506  
"2023-02-12",221,356,187,237,13673  
"2023-02-13",1449,2681,1306,1722,207955  
"2023-02-14",1724,3075,1440,1962,211402  
"2023-02-15",4226,13653,3559,5915,1043890  
"2023-02-16",5793,18555,4796,7969,1496917  
"2023-02-17",4941,16870,4098,6987,1444726
```

--------------------------------

### GET /api/v1/sites/:site_id - Get site details

Source: https://plausible.io/docs/sites-api

Retrieves details of a site, including its tracker script configuration and the tracker script ID. The account must have access to the site.

```bash
curl -X GET https://plausible.io/api/v1/sites/test-domain.com \
  -H "Authorization: Bearer ${TOKEN}"  

```

```json
{  
    "domain": "test-domain.com",  
    "timezone": "Europe/London",  
    "custom_properties": ["logged_in"],  
    "tracker_script_configuration": {  
        "id": "pa-1iQepzD1J73BaHey2csUp",  
        "installation_type": null,  
        "track_404_pages": false,  
        "hash_based_routing": false,  
        "outbound_links": false,  
        "file_downloads": false,  
        "revenue_tracking": false,  
        "tagged_events": false,  
        "form_submissions": false,  
        "pageview_props": false  
    }  
}  

```
Tokens:
Raw