# Plausible

> Read a Plausible Analytics site from a workflow: totals, visitors over time, current visitors, and breakdowns by page, source, channel, campaign, country, device, browser and goal - and send events back in for things that happen where a tracking script cannot see them. Works with Plausible Cloud and with self-hosted Community Edition.

App · Analytics · 20 actions. Web page: https://docs.lodol.com/docs/integrations/plausible

## Actions

### Get current visitors

How many people are on the site right now, as the count of unique visitors in the last few minutes. Returned on 'visitors'. Use it to watch a launch, or to alert when traffic spikes or falls away.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Minutes back (`minutes`, number): How far back 'right now' reaches, 1-1440. Defaults to 5, which is what Plausible's own 'current visitors' counts. From 1 to 1440. Default: `5`.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `minutes` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)
- `visitors` (number)
- `window_end` (text)
- `window_start` (text)

**Example output**

```json
{
  "count": 1,
  "date_range": [
    "2026-09-12T09:55:00+00:00",
    "2026-09-12T10:00:00+00:00"
  ],
  "dimensions": [],
  "meta": {},
  "metrics": [
    "visitors"
  ],
  "minutes": 5,
  "results": [
    {
      "visitors": 12
    }
  ],
  "site_id": "example.com",
  "total_rows": null,
  "visitors": 12,
  "window_end": "2026-09-12T10:00:00+00:00",
  "window_start": "2026-09-12T09:55:00+00:00"
}
```

### Get site totals

The numbers across the top of a Plausible dashboard - unique visitors, visits, pageviews, bounce rate and average visit duration - for a period you choose. One number per metric, returned on 'totals' so a later step can read totals.visitors directly. Add filters to ask the same question about a slice of the traffic.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, pageviews, bounce_rate, visit_duration. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `pageviews`, `views_per_visit` (Pageviews per visit), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `events` (Events (pageviews + custom)). Default: `["visitors", "visits", "pageviews", "bounce_rate", "visit_duration"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)
- `totals` (object): One value per metric asked for, for the whole period - for example {'visitors': 1204, 'bounce_rate': 41}.

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [],
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "visits",
    "pageviews",
    "bounce_rate",
    "visit_duration"
  ],
  "results": [
    {
      "bounce_rate": 38,
      "pageviews": 4120,
      "visit_duration": 94,
      "visitors": 1840,
      "visits": 2012
    }
  ],
  "site_id": "example.com",
  "total_rows": 1,
  "totals": {
    "bounce_rate": 38,
    "pageviews": 4120,
    "visit_duration": 94,
    "visitors": 1840,
    "visits": 2012
  }
}
```

### Get visitors over time

Traffic split into time buckets - by hour, day, week or month - for charting a period or comparing one day against the next. Every bucket valid for the period is also returned on 'time_labels', including the empty ones the rows leave out, so a chart has a complete axis.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Bucket size (`interval`, text): How wide each bucket is. 'Automatic' lets Plausible pick a sensible one for the period. Defaults to daily. One of: `time` (Automatic), `time:hour` (Hourly), `time:day` (Daily), `time:week` (Weekly), `time:month` (Monthly). Default: `time:day`.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, pageviews. Pageviews per visit is not offered here - Plausible does not support it alongside a time bucket. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `pageviews`, `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `events` (Events (pageviews + custom)). Default: `["visitors", "pageviews"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `interval` (text)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `results` (list)
- `site_id` (text)
- `time_labels` (list)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "time:day"
  ],
  "interval": "time:day",
  "meta": {
    "time_labels": [
      "2026-09-08",
      "2026-09-09"
    ],
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "pageviews"
  ],
  "results": [
    {
      "bucket": "2026-09-08",
      "pageviews": 512,
      "visitors": 240
    },
    {
      "bucket": "2026-09-09",
      "pageviews": 601,
      "visitors": 288
    }
  ],
  "site_id": "example.com",
  "time_labels": [
    "2026-09-08",
    "2026-09-09"
  ],
  "total_rows": 2
}
```

### List acquisition channels

Traffic grouped into channels - organic search, paid search, referral, social, email, direct. The level above individual sources, and the one to report on month over month. Plausible works the channel out itself from the referrer and the campaign tags.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, bounce_rate. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors). Default: `["visitors", "visits", "bounce_rate"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many channels to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many channels before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "visit:channel"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "visits",
    "bounce_rate"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "bounce_rate": 42,
      "channel": "Organic Search",
      "visitors": 1120,
      "visits": 1240
    },
    {
      "bounce_rate": 35,
      "channel": "Direct",
      "visitors": 480,
      "visits": 502
    }
  ],
  "site_id": "example.com",
  "total_rows": 2
}
```

### List browsers

Visitors by browser, or by browser version if you need to know whether anyone is still on an old one.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Group by (`browser_dimension`, text): Browsers, or individual browser versions. Defaults to browsers. One of: `visit:browser` (Browser), `visit:browser_version` (Browser version). Default: `visit:browser`.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, percentage. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `percentage` (Percentage of visitors). Default: `["visitors", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many browsers to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many browsers before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "visit:browser"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "browser": "Chrome",
      "percentage": 62.0,
      "visitors": 1140
    },
    {
      "browser": "Safari",
      "percentage": 22.8,
      "visitors": 420
    }
  ],
  "site_id": "example.com",
  "total_rows": 2
}
```

### List campaign traffic

Campaign traffic broken down by whichever UTM tag you pick - source, medium, campaign, content or term. One action rather than five, because the question is always the same and only the tag changes.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Campaign tag (`utm_dimension`, text): Which UTM tag to group by. Defaults to utm_source. One of: `visit:utm_source` (utm_source), `visit:utm_medium` (utm_medium), `visit:utm_campaign` (utm_campaign), `visit:utm_content` (utm_content), `visit:utm_term` (utm_term). Default: `visit:utm_source`.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, bounce_rate. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors). Default: `["visitors", "visits", "bounce_rate"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many campaign values to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many campaign values before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:utm_source"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "visits",
    "bounce_rate"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "bounce_rate": 29,
      "utm_source": "newsletter",
      "visitors": 142,
      "visits": 150
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List cities

Visitors by city, by name. Plausible also has a numeric city ID, which is no use in a workflow, so the name is what this returns.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, percentage. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `percentage` (Percentage of visitors). Default: `["visitors", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many cities to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many cities before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:city_name"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "city_name": "London",
      "percentage": 16.4,
      "visitors": 301
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List countries

Visitors by country, by name rather than by code. Turn on 'Include country codes' as well if a downstream system wants the two-letter ISO code.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Include country codes (`include_country_codes`, true/false): Also return the two-letter ISO 3166-1 code beside each country name, as 'country'. Default: `false`.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, percentage. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `percentage` (Percentage of visitors). Default: `["visitors", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many countries to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many countries before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "visit:country_name"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "country_name": "United Kingdom",
      "percentage": 34.8,
      "visitors": 640
    },
    {
      "country_name": "Estonia",
      "percentage": 11.4,
      "visitors": 210
    }
  ],
  "site_id": "example.com",
  "total_rows": 2
}
```

### List custom property values

The values one custom property took, and how many visitors saw each - the author of a post, the plan on a pricing page, whatever your events carry. Give the property's bare name, such as 'author'. Custom properties are a Business plan feature and a site with none returns no rows.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Property name (`property_name`, text, required): The custom property's name on its own, such as 'author' - not 'event:props:author'.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, events, percentage. One or more of: `visitors` (Unique visitors), `events`, `percentage` (Percentage of visitors). Default: `["visitors", "events", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `events`, `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many values to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many values before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `property_name` (text)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "event:props:author"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "events",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "property_name": "author",
  "results": [
    {
      "author": "Anna",
      "events": 410,
      "percentage": 17.4,
      "visitors": 320
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List device sizes

Visitors by device size - desktop, laptop, tablet or mobile. Plausible works these out from the screen width, so they are size buckets rather than detected hardware.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, percentage. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `percentage` (Percentage of visitors). Default: `["visitors", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many device sizes to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many device sizes before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "visit:device"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "device": "Desktop",
      "percentage": 65.8,
      "visitors": 1210
    },
    {
      "device": "Mobile",
      "percentage": 27.4,
      "visitors": 505
    }
  ],
  "site_id": "example.com",
  "total_rows": 2
}
```

### List entry pages

The pages visits started on - the first thing each visitor saw. Bounce rate here needs Plausible Cloud or a self-hosted Community Edition on 3.1.0 or newer; drop it from the metrics on an older instance.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, visit_duration. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors). Default: `["visitors", "visits", "visit_duration"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many entry pages to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many entry pages before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:entry_page"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "visits",
    "visit_duration"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "entry_page": "/",
      "visit_duration": 94,
      "visitors": 1602,
      "visits": 1780
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List exit pages

The pages visits ended on - the last thing each visitor saw before leaving.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, visit_duration. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors). Default: `["visitors", "visits", "visit_duration"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many exit pages to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many exit pages before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:exit_page"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "visits",
    "visit_duration"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "exit_page": "/pricing",
      "visit_duration": 54,
      "visitors": 430,
      "visits": 468
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List goal conversions

How each goal is converting - unique visitors, total conversions and conversion rate per goal. The revenue metrics are off by default and only work on a site with revenue goals configured; asking for them on a site without any is refused by Plausible.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, events, conversion_rate. One or more of: `visitors` (Unique visitors), `events` (Conversions (events)), `conversion_rate` (Conversion rate (%)), `group_conversion_rate` (Group conversion rate (%)), `total_revenue` (Total revenue (revenue goals only)), `average_revenue` (Average revenue (revenue goals only)). Default: `["visitors", "events", "conversion_rate"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `events` (Conversions (events)), `conversion_rate` (Conversion rate (%)), `group_conversion_rate` (Group conversion rate (%)), `total_revenue` (Total revenue (revenue goals only)), `average_revenue` (Average revenue (revenue goals only)).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many goals to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many goals before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "event:goal"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "events",
    "conversion_rate"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "conversion_rate": 4.6,
      "events": 91,
      "goal": "Signup",
      "visitors": 84
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List operating systems

Visitors by operating system, or by OS version.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Group by (`os_dimension`, text): Operating systems, or individual versions. Defaults to operating systems. One of: `visit:os` (Operating system), `visit:os_version` (Operating system version). Default: `visit:os`.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, percentage. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `percentage` (Percentage of visitors). Default: `["visitors", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many operating systems to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many operating systems before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:os"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "os": "Mac",
      "percentage": 39.7,
      "visitors": 730
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List referrers

The raw referring hosts visits arrived from, before Plausible tidies them into source names. Use this when you need the actual domain that linked to you.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, bounce_rate. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors). Default: `["visitors", "visits", "bounce_rate"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many referrers to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many referrers before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:referrer"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "visits",
    "bounce_rate"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "bounce_rate": 61,
      "referrer": "news.ycombinator.com",
      "visitors": 208,
      "visits": 219
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List regions

Visitors by region or state, by name. Plausible works the region out from the IP address and does not store it, so coverage is good but not complete.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, percentage. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `percentage` (Percentage of visitors). Default: `["visitors", "percentage"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many regions to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many regions before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "visit:region_name"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors",
    "percentage"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "percentage": 28.3,
      "region_name": "England",
      "visitors": 520
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### List top pages

The most-visited pages, with visitors and pageviews for each. This is the one breakdown where scroll depth and time on page are available, because both are measured per page.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, pageviews, bounce_rate. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `pageviews`, `bounce_rate` (Bounce rate (%)), `events`, `percentage` (Percentage of visitors), `scroll_depth` (Scroll depth), `time_on_page` (Time on page (seconds)). Default: `["visitors", "pageviews", "bounce_rate"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `pageviews`, `bounce_rate` (Bounce rate (%)), `events`, `percentage` (Percentage of visitors), `scroll_depth` (Scroll depth), `time_on_page` (Time on page (seconds)).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many pages to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many pages before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "event:page"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "pageviews",
    "bounce_rate"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "bounce_rate": 38,
      "page": "/",
      "pageviews": 2410,
      "visitors": 1840
    },
    {
      "bounce_rate": 21,
      "page": "/pricing",
      "pageviews": 740,
      "visitors": 612
    }
  ],
  "site_id": "example.com",
  "total_rows": 2
}
```

### List traffic sources

Where visitors came from, as the tidied-up source names Plausible shows on its dashboard - 'Google', 'Hacker News'. Use 'List referrers' instead for the raw referring host.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors, visits, bounce_rate. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors). Default: `["visitors", "visits", "bounce_rate"]`.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `percentage` (Percentage of visitors).
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many sources to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many sources before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 2,
  "date_range": "7d",
  "dimensions": [
    "visit:source"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 2
  },
  "metrics": [
    "visitors",
    "visits",
    "bounce_rate"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "bounce_rate": 44,
      "source": "Google",
      "visitors": 910,
      "visits": 1002
    },
    {
      "bounce_rate": 61,
      "source": "Hacker News",
      "visitors": 208,
      "visits": 219
    }
  ],
  "site_id": "example.com",
  "total_rows": 2
}
```

### Run a stats query

Ask Plausible anything its Stats API can answer: pick the metrics and the dimensions to group by yourself. Use this when no other step here is the shape you want - two dimensions at once, or a dimension the other steps do not offer. Plausible's own rules still apply: 'percentage' needs a dimension, scroll depth and time on page need event:page, and the conversion and revenue metrics need event:goal.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Metrics (`metrics`, text): Which numbers to return. Leave blank for visitors. One or more of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `pageviews`, `views_per_visit` (Pageviews per visit), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `events` (Events (pageviews + custom)), `percentage` (Percentage of visitors (needs a dimension)), `scroll_depth` (Scroll depth (needs event:page)), `time_on_page` (Time on page, seconds (needs event:page)), and 4 more. Default: `["visitors"]`.
- Group by (`dimensions`, text): What to break the numbers down by. Leave blank for one total row. A custom property can be typed in as 'event:props:<name>'. One or more of: `event:goal` (Goal), `event:page` (Page), `event:hostname` (Hostname), `visit:entry_page` (Entry page), `visit:exit_page` (Exit page), `visit:source` (Source), `visit:referrer` (Referrer), `visit:channel` (Acquisition channel), `visit:utm_medium` (utm_medium), `visit:utm_source` (utm_source), and 19 more.
- Period (`date_range`, text): Which period to report on. Ignored when both dates below are set. Defaults to 7d. One of: `day` (Today), `24h` (The last 24 hours), `7d` (The last 7 days), `28d` (The last 28 days), `month` (This calendar month), `6mo` (The last 6 months), `12mo` (The last 12 months), `year` (This calendar year), `all` (All time). Default: `7d`.
- From (`start_date`, date): The first day to include. Set this and 'To' together to use an exact range instead of the period above; leave both blank to use the period.
- To (`end_date`, date): The last day to include. Has to be set together with 'From'.
- Filters (`filters`, list): Narrow the query, using Plausible's filter syntax: a list of [operator, dimension, values] triples, such as [["is", "visit:country", ["EE", "GB"]]]. The operators are is, is_not, contains, contains_not, matches, matches_not, and they can be nested inside and, or and not.
- Sort by (`sort_by`, text): Which metric to order the rows by. It is added to the returned metrics if it is not there already. Defaults to visitors. One of: `visitors` (Unique visitors), `visits` (Visits (sessions)), `pageviews`, `views_per_visit` (Pageviews per visit), `bounce_rate` (Bounce rate (%)), `visit_duration` (Visit duration (seconds)), `events` (Events (pageviews + custom)), `percentage` (Percentage of visitors (needs a dimension)), `scroll_depth` (Scroll depth (needs event:page)), `time_on_page` (Time on page, seconds (needs event:page)), and 4 more.
- Order (`sort_direction`, text): Which way round to sort. Defaults to highest first. One of: `desc` (Highest first), `asc` (Lowest first). Default: `desc`.
- How many (`limit`, number): How many rows to return, 1-10000. Defaults to 100. From 1 to 10000.
- Skip (`offset`, number): Skip this many rows before the page begins. Read 'next_offset' from the result to get the next page. From 0 to 1000000.
- Include imported data (`include_imports`, true/false): Count data imported from Google Analytics or a CSV alongside what Plausible measured itself. Off by default, which is Plausible's own default. Check 'meta' on the result if the numbers look wrong - Plausible reports there when it had to skip an import. Default: `false`.

**Outputs**

- `count` (number)
- `date_range`: The period the query covered: either the shorthand that was used ('7d'), or the two dates it ran between.
- `dimensions` (list)
- `has_more` (true/false)
- `limit` (number)
- `meta` (object): Plausible's own metadata for the query. Its keys are conditional: 'total_rows' and 'time_labels' only appear when they were asked for, and the 'imports_*' keys only on a site with imported data.
- `metrics` (list)
- `next_offset` (number)
- `offset` (number)
- `results` (list)
- `site_id` (text)
- `total_rows` (number)

**Example output**

```json
{
  "count": 1,
  "date_range": "7d",
  "dimensions": [
    "event:page"
  ],
  "has_more": false,
  "limit": 100,
  "meta": {
    "total_rows": 1
  },
  "metrics": [
    "visitors"
  ],
  "next_offset": null,
  "offset": 0,
  "results": [
    {
      "page": "/pricing",
      "visitors": 612
    }
  ],
  "site_id": "example.com",
  "total_rows": 1
}
```

### Send event

Record a pageview or a custom event against a site - a signup completing, an order being placed, anything that happens somewhere a tracking script cannot see. This is the one step here that works on every Plausible plan, because the events endpoint needs no API key. Two things to know: Plausible answers 'accepted' without promising to count it, so check 'dropped' on the result; and it works out who the visitor is from the User-Agent and IP address it is sent, so leaving both blank attributes every event to this server as one visitor.

**Inputs**

- Site (`site_id`, text, required): The site's domain exactly as it is registered in Plausible, such as 'example.com'. It is the name at the top of the site's dashboard. Pasting the full URL works too.
- Event name (`name`, text): What happened. Use the goal's exact name to record a conversion, or 'pageview' - the one reserved name - to record a page view. Defaults to 'pageview'. Default: `pageview`.
- Page URL (`url`, text, required): The address of the page the event happened on. A path beginning with '/' is completed with the site's own domain.
- Referrer (`referrer`, text): Where the visitor came from, if you know it. Feeds the sources and channels breakdowns.
- Custom properties (`props`, object): Extra fields to record with the event, which you can then break down by. At most 30 of them.
- Revenue (`revenue`, object): Money this event brought in, as {"currency": "USD", "amount": 15.99}. Only counted when the goal is set up as a revenue goal in Plausible.
- Counts as interaction (`interactive`, true/false): Whether this event stops the visit counting as a bounce. Leave blank for Plausible's own default.
- Visitor's browser (`user_agent`, text): The visitor's User-Agent string. Plausible works out who the visitor is from this, so pass the real one through when you have it. Left blank, every event from this workflow looks like the same datacentre visitor and may be discarded as a bot.
- Visitor's IP address (`client_ip`, text): The visitor's IP address, used for the country, region and city breakdowns. Plausible hashes it and does not store it. Left blank, the event is located wherever this server is.

**Outputs**

- `dropped` (true/false)
- `interactive` (true/false)
- `name` (text)
- `props` (object)
- `referrer` (text)
- `revenue` (object)
- `site_id` (text)
- `status` (text)
- `url` (text)
- `user_agent` (text)
- `warning` (text)

**Example output**

```json
{
  "dropped": false,
  "interactive": null,
  "name": "Signup",
  "props": {
    "plan": "pro"
  },
  "referrer": null,
  "revenue": null,
  "site_id": "example.com",
  "status": "accepted",
  "url": "https://example.com/welcome",
  "user_agent": "Lodol-Workflow/1.0",
  "warning": null
}
```