Stats v2 queries

The consolidated /api/v2/query endpoint unlocks dimensions, ordering, pagination and richer metrics. Drive it from the same builder with dimensions(), orderBy(), include(), array filter()s and the run() terminal:

use RoundlyConsulting\Plausible\Enums\Dimension;
use RoundlyConsulting\Plausible\Enums\Metric;

$result = Plausible::stats()
    ->for('my-site.com')
    ->metrics(Metric::Visitors, Metric::BounceRate)
    ->dimensions(Dimension::EventPage)
    ->filter(['is', 'visit:browser', ['Chrome']])
    ->orderBy(['visitors', 'desc'])
    ->include(['imports' => true])
    ->between(now()->subDays(7), now())
    ->perPage(10)
    ->page(2)                                      // pagination: limit 10, offset 10
    ->run();                                       // -> QueryResult

foreach ($result->rows() as $row) {
    $row->dimension(0);   // e.g. "/pricing"
    $row->metric(0);      // visitors
    $row->metric(1);      // bounce_rate
}

$result->meta();          // the response's meta block
$result->query();         // the query as Plausible ran it
$result->collect();       // Collection<int, QueryRow>
$result->response();      // the raw Response

Each QueryRow holds positional values: metric($i) follows the order of metrics(), dimension($i) the order of dimensions(). perPage() and page() become the request’s pagination as limit and offset.

Time buckets

In v2, bucket over time with a time:* dimension (TimeHour, TimeDay, TimeWeek, TimeMonth) instead of interval():

// Bucket by day with a time:* dimension instead of interval()
$daily = Plausible::stats()
    ->for('my-site.com')
    ->metrics(Metric::Visitors)
    ->dimensions(Dimension::TimeDay)
    ->last30Days()
    ->run();

Date ranges

run() sends named periods as a relative date_range, and a between() or since() range as [start, end] ISO dates — since() closes the range at today. A bare Period::Custom without dates falls back to 30d.

Explicit QueryRequest

Or build the request yourself and call runQuery():

use RoundlyConsulting\Plausible\Enums\Dimension;
use RoundlyConsulting\Plausible\Enums\Metric;
use RoundlyConsulting\Plausible\Requests\Stats\QueryRequest;

$result = Plausible::stats()->runQuery(QueryRequest::make(
    site: 'my-site.com',
    metrics: [Metric::Visitors, Metric::Pageviews],
    dateRange: ['2026-01-01', '2026-01-31'],       // or '30d' / Period::ThirtyDays
    dimensions: [Dimension::VisitCountry],
    orderBy: [['visitors', 'desc']],
    limit: 25,
));                                                // -> QueryResult

Stats v2 is available on Plausible Cloud and recent self-hosted versions. Older self-hosted instances may only expose the v1 endpoints.

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages