Timeseries Stats

The timeseries endpoint allows you to retrieve statistics over time, broken down by a specified time interval. Use this to create charts and graphs showing how your traffic and engagement metrics change over time.

Endpoint

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

Authentication

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

Authorization: Bearer YOUR_API_KEY

Query Parameters

site_id

string

required

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

period

string

The time period for the query. Valid values:

day - Current day
7d - Last 7 days
30d - Last 30 days
month - Current month
6mo - Last 6 months
12mo - Last 12 months
custom - Custom date range (requires date parameter)

Defaults to 30d if not specified.

date

string

Date or date range in ISO-8601 format.For single date periods: 2024-01-01For custom periods: 2024-01-01,2024-01-31 (comma-separated start and end dates)Required when period=custom.

interval

string

The time interval for grouping data points. Valid values:

day - Group by day
month - Group by month

If not specified, the interval is automatically selected based on the period:

Periods up to 1 day use hour intervals (in the dashboard)
Periods up to 6 months use day intervals
Longer periods use month intervals

Note: The date value is deprecated and automatically converted to day.

metrics

string

Comma-separated list of metrics to retrieve. Defaults to visitors if not specified.Available metrics:

visitors - Unique visitors
visits - Total visits (sessions)
pageviews - Total pageviews
events - Total events
bounce_rate - Bounce rate percentage
visit_duration - Average visit duration in seconds
views_per_visit - Average pageviews per visit
conversion_rate - Goal conversion rate (requires goal filter)
time_on_page - Average time on page in seconds (requires page filter)

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

filters

string

Filter the data by specific dimensions. Format: dimension==value for equality or dimension!=value for negation.Multiple filters can be combined with semicolons (;).Multiple values for the same dimension can be combined with pipes (|).Wildcard matching is supported using asterisks (*).Examples:

event:page==/blog - Filter to a specific page
visit:country==US - Filter to United States traffic
visit:source==Google|Twitter - Filter to Google or Twitter traffic
event:page==/blog** - Wildcard match for blog pages

compare

string

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

Properties

Available dimensions for filtering:

Event Properties

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

Visit (Session) Properties

visit:source - Traffic source
visit:channel - Traffic channel
visit:country - Country code (ISO 3166-1 alpha-2)
visit:region - Region code
visit:city - City name
visit:entry_page - Entry page path
visit:exit_page - Exit page path
visit:referrer - Referrer URL
visit:utm_medium - UTM medium
visit:utm_source - UTM source
visit:utm_campaign - UTM campaign
visit:utm_content - UTM content
visit:utm_term - UTM term
visit:device - Device type (Desktop, Mobile, Tablet)
visit:os - Operating system
visit:os_version - Operating system version
visit:browser - Browser name
visit:browser_version - Browser version

Metric Constraints

Certain metrics have specific requirements:

conversion_rate - Can only be queried with a goal filter (event:goal==)
time_on_page - Can only be queried with a page filter
Session metrics (visits, bounce_rate, visit_duration, views_per_visit) - Cannot be queried when filtering by event:name, event:goal, or custom event properties

Response

results

array

Array of time series data points, one for each interval in the specified period.

Show properties

date

string

The date or timestamp for this data point.Format varies by interval:

For day interval: ISO date string (e.g., "2024-01-15")
For month interval: Month string (e.g., "2024-01-01")

[metric]

number

Metric values as specified in the metrics parameter.One field for each requested metric (e.g., visitors, pageviews, bounce_rate).Default value is returned for intervals with no data (0 for counts, 0.0 for rates, null for durations).

warning

string

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

Examples

Basic Timeseries

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

{
  "results": [
    {
      "date": "2024-01-08",
      "visitors": 1234,
      "pageviews": 2876
    },
    {
      "date": "2024-01-09",
      "visitors": 1456,
      "pageviews": 3201
    },
    {
      "date": "2024-01-10",
      "visitors": 1123,
      "pageviews": 2543
    },
    {
      "date": "2024-01-11",
      "visitors": 1567,
      "pageviews": 3456
    },
    {
      "date": "2024-01-12",
      "visitors": 1789,
      "pageviews": 3987
    },
    {
      "date": "2024-01-13",
      "visitors": 1345,
      "pageviews": 2987
    },
    {
      "date": "2024-01-14",
      "visitors": 1654,
      "pageviews": 3654
    }
  ]
}

Monthly Timeseries with Custom Range

curl "https://plausible.io/api/v1/stats/timeseries?site_id=example.com&period=custom&date=2024-01-01,2024-06-30&interval=month&metrics=visitors,visits,bounce_rate" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": [
    {
      "date": "2024-01-01",
      "visitors": 45678,
      "visits": 52341,
      "bounce_rate": 62.3
    },
    {
      "date": "2024-02-01",
      "visitors": 48234,
      "visits": 55123,
      "bounce_rate": 59.8
    },
    {
      "date": "2024-03-01",
      "visitors": 51234,
      "visits": 58976,
      "bounce_rate": 58.4
    },
    {
      "date": "2024-04-01",
      "visitors": 49876,
      "visits": 57234,
      "bounce_rate": 60.1
    },
    {
      "date": "2024-05-01",
      "visitors": 53421,
      "visits": 61234,
      "bounce_rate": 57.9
    },
    {
      "date": "2024-06-01",
      "visitors": 55123,
      "visits": 63456,
      "bounce_rate": 56.2
    }
  ]
}

With Filters

curl "https://plausible.io/api/v1/stats/timeseries?site_id=example.com&period=30d&metrics=visitors,events&filters=visit:country==US;event:page==/pricing" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": [
    {
      "date": "2024-01-01",
      "visitors": 234,
      "events": 456
    },
    {
      "date": "2024-01-02",
      "visitors": 198,
      "events": 387
    },
    {
      "date": "2024-01-03",
      "visitors": 267,
      "events": 512
    }
  ]
}

Goal Conversion Over Time

curl "https://plausible.io/api/v1/stats/timeseries?site_id=example.com&period=7d&metrics=visitors,conversion_rate&filters=event:goal==Signup" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "results": [
    {
      "date": "2024-01-08",
      "visitors": 234,
      "conversion_rate": 3.2
    },
    {
      "date": "2024-01-09",
      "visitors": 267,
      "conversion_rate": 3.8
    },
    {
      "date": "2024-01-10",
      "visitors": 198,
      "conversion_rate": 2.9
    },
    {
      "date": "2024-01-11",
      "visitors": 312,
      "conversion_rate": 4.1
    },
    {
      "date": "2024-01-12",
      "visitors": 289,
      "conversion_rate": 3.5
    },
    {
      "date": "2024-01-13",
      "visitors": 245,
      "conversion_rate": 3.3
    },
    {
      "date": "2024-01-14",
      "visitors": 278,
      "conversion_rate": 3.7
    }
  ]
}

Error Responses

error

string

Error message describing what went wrong

Common Errors

400 Bad Request - Invalid interval

{
  "error": "Error parsing `interval` parameter: invalid interval `week`. Valid intervals are `day`, `month`"
}

400 Bad Request - Invalid period

{
  "error": "Error parsing `period` parameter: invalid period `invalid`. Please find accepted values in our docs: https://plausible.io/docs/stats-api#time-periods"
}

400 Bad Request - Invalid date format

{
  "error": "Invalid format for `date` parameter. When using a custom period, please include two ISO-8601 formatted dates joined by a comma. See https://plausible.io/docs/stats-api#time-periods"
}

400 Bad Request - Metric validation failed

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

Notes

The timeseries endpoint always returns a data point for each interval in the specified period, even if there was no traffic. Missing data is filled with default values (0 for counts, 0.0 for rates, null for durations).
When using comparison mode, the comparison data is not included in the timeseries response format. Use the aggregate or breakdown endpoints for comparison data.
The response is ordered chronologically by date.

Overview

Stats API

Sites API

Events API

Goals API

Endpoint

Authentication

Query Parameters

Properties

Event Properties

Visit (Session) Properties

Metric Constraints

Response

Examples

Basic Timeseries

Monthly Timeseries with Custom Range

With Filters

Goal Conversion Over Time

Error Responses

Common Errors

Notes

Build docs developers (and LLMs) love

Overview

Stats API

Sites API

Events API

Goals API

​Endpoint

​Authentication

​Query Parameters

​Properties

​Event Properties

​Visit (Session) Properties

​Metric Constraints

​Response

​Examples

​Basic Timeseries

​Monthly Timeseries with Custom Range

​With Filters

​Goal Conversion Over Time

​Error Responses

​Common Errors

​Notes

Build docs developers (and LLMs) love

Endpoint

Authentication

Query Parameters

Properties

Event Properties

Visit (Session) Properties

Metric Constraints

Response

Examples

Basic Timeseries

Monthly Timeseries with Custom Range

With Filters

Goal Conversion Over Time

Error Responses

Common Errors

Notes