Health check

Verify configuration and connectivity without throwing:

Plausible::ping();                  // bool — reachable AND the key is accepted
Plausible::ping('my-site.com');     // same, verified against this site

$health = Plausible::health();      // HealthResult — never throws
$health = Plausible::health('my-site.com');

$health->ok();                      // configured, reachable and the key accepted
$health->isConfigured();            // url and key are both set
$health->hasUrl;                    // bool
$health->hasKey;                    // bool
$health->reachable;                 // the instance answered (no connection error, 5xx or 404)
$health->authorized;                // the probe was answered 2xx with the key
$health->status;                    // ?int — HTTP status of the probe, null when not reached
$health->message;                   // human-readable status

health() first checks that url and key are set. The probe then depends on what it can verify:

• With a site — the argument, else PLAUSIBLE_SITE — it calls the Stats API (GET /api/v1/stats/realtime/visitors), which a Stats API key can reach.
• Without one it calls the Sites API (GET /api/v1/sites), which only a Sites API key can reach; a refused Stats key is reported as such, with the fix — set PLAUSIBLE_SITE or pass a site.

Only a 2xx passes. A server error (5xx) or a 404 — a wrong PLAUSIBLE_URL — marks the instance unreachable; a 401, 402 or 403 means the key was refused, and a 429 means the key is rate-limited and could not be verified. A connection failure is reported in the message, never thrown. ping() is shorthand for health()->ok().

Artisan command

A matching command reports the same — pass --site= to verify the key against that site’s Stats API:

php artisan plausible:health
php artisan plausible:health --site=my-site.com

Plausible health check
  URL configured: yes
  Key configured: yes
  Reachable:      yes
  Key accepted:   yes
  HTTP status:    200
Plausible is reachable and the API key can read stats for my-site.com.

It exits non-zero unless ok() — configured, reachable and the key accepted — so drop it into a deploy pipeline as a post-deploy check. php artisan about also shows a Plausible section (see Configuration).