---
title: "Stats v2 queries — Plausible for Laravel | Roundly"
description: "Drive the /api/v2/query endpoint with dimensions, ordering, includes and pagination, and read positional QueryResult rows."
url: https://roundly-consulting.com/open-source/docs/plausible-for-laravel/query-api
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Plausible for Laravel](https://roundly-consulting.com/open-source/docs/plausible-for-laravel.md)

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

```php
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: limit is sent whenever an offset is (page() above 1) or perPage() was called, so page(2) returns rows 101–200. With neither, no pagination is sent and Plausible’s v2 default of 10,000 rows applies.

## Time buckets

In v2, bucket over time with a time:\* dimension (TimeHour, TimeDay, TimeWeek, TimeMonth) instead of interval() — the way to get hourly or weekly buckets, which the v1 timeseries() refuses:

```php
// 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 — year and all included, so allTime() works here — 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():

```php
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](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## 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](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/plausible-for-laravel.md)