---
title: "Configuration — Plausible for Laravel | Roundly"
description: "Every config key, its default and its env variable — instance, default site, HTTP, rate limits, tracking and script."
url: https://roundly-consulting.com/open-source/docs/plausible-for-laravel/configuration
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)

# Configuration

The published config/plausible.php in full:

```php
<?php

declare(strict_types=1);

return [
    'url' => env('PLAUSIBLE_URL'),

    'key' => env('PLAUSIBLE_API_KEY'),

    'site' => env('PLAUSIBLE_SITE'),

    'timeout' => env('PLAUSIBLE_TIMEOUT', 10),

    'retry' => [
        'times' => env('PLAUSIBLE_RETRY_TIMES', 0),
        'sleep_ms' => env('PLAUSIBLE_RETRY_SLEEP', 100),
    ],

    'rate_limits' => [
        'stats' => [
            'enabled' => env('PLAUSIBLE_STATS_RATELIMIT_ENABLED', true),
            'owner' => env('PLAUSIBLE_RATELIMIT_OWNER', 'app'),
            'limit' => env('PLAUSIBLE_STATS_RATELIMIT', 600),
            'per' => env('PLAUSIBLE_STATS_RATELIMIT_PER', 'hour'),
            'adaptive' => env('PLAUSIBLE_STATS_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('PLAUSIBLE_STATS_RATELIMIT_MAX_WAIT'),
            'jitter' => env('PLAUSIBLE_STATS_RATELIMIT_JITTER'),
            'per_site' => env('PLAUSIBLE_STATS_RATELIMIT_PER_SITE', false),
        ],

        'events' => [
            'enabled' => env('PLAUSIBLE_EVENTS_RATELIMIT_ENABLED', true),
            'owner' => env('PLAUSIBLE_RATELIMIT_OWNER', 'app'),
            'limit' => env('PLAUSIBLE_EVENTS_RATELIMIT', 6000),
            'per' => env('PLAUSIBLE_EVENTS_RATELIMIT_PER', 'minute'),
            'adaptive' => env('PLAUSIBLE_EVENTS_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('PLAUSIBLE_EVENTS_RATELIMIT_MAX_WAIT'),
            'jitter' => env('PLAUSIBLE_EVENTS_RATELIMIT_JITTER'),
            'per_site' => env('PLAUSIBLE_EVENTS_RATELIMIT_PER_SITE', true),
        ],

        'sites' => [
            'enabled' => env('PLAUSIBLE_SITES_RATELIMIT_ENABLED', true),
            'owner' => env('PLAUSIBLE_RATELIMIT_OWNER', 'app'),
            'limit' => env('PLAUSIBLE_SITES_RATELIMIT', 60),
            'per' => env('PLAUSIBLE_SITES_RATELIMIT_PER', 'hour'),
            'adaptive' => env('PLAUSIBLE_SITES_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('PLAUSIBLE_SITES_RATELIMIT_MAX_WAIT'),
            'jitter' => env('PLAUSIBLE_SITES_RATELIMIT_JITTER'),
            'per_site' => env('PLAUSIBLE_SITES_RATELIMIT_PER_SITE', false),
        ],
    ],

    'tracking' => [
        'queue' => env('PLAUSIBLE_TRACKING_QUEUE', true),

        'user_agent' => env('PLAUSIBLE_TRACKING_USER_AGENT', 'PlausibleForLaravel'),

        'ip_address' => env('PLAUSIBLE_TRACKING_IP', '127.0.0.1'),
    ],

    'script' => [
        'domain' => env('PLAUSIBLE_SCRIPT_DOMAIN'),

        'src' => env('PLAUSIBLE_SCRIPT_SRC', 'https://plausible.io/js/script.js'),
    ],
];
```

## Every key

| Key | Default | Env | Purpose |
| --- | --- | --- | --- |
| `url` | — | PLAUSIBLE\_URL | Base URL of your Plausible instance, e.g. https://plausible.io or your self-hosted domain. Required. |
| `key` | — | PLAUSIBLE\_API\_KEY | Your Plausible API key, sent as a Bearer token on Stats and Sites requests. Required for those; event capture neither needs nor sends it. See API keys below. |
| `site` | null | PLAUSIBLE\_SITE | Optional default site (domain). Used by stats()->query(), the events helpers, the middleware, the Trackable trait, the script tag (when script.domain is unset) and the health check. |
| `timeout` | 10 | PLAUSIBLE\_TIMEOUT | Per-request timeout in seconds, at least 1. |
| `retry.times` | 0 | PLAUSIBLE\_RETRY\_TIMES | Retries after the first attempt (1 = two attempts), only for a failed connection or a 5xx — never a 4xx, and never an event whose request timed out. 0 disables retries. |
| `retry.sleep_ms` | 100 | PLAUSIBLE\_RETRY\_SLEEP | Milliseconds to wait between retries. |
| `rate_limits.*` | see Rate limiting | PLAUSIBLE\_\*\_RATELIMIT\* | Per-surface client-side rate limiting for stats, events and sites. |
| `tracking.queue` | true | PLAUSIBLE\_TRACKING\_QUEUE | Queue captures from the middleware and the Trackable trait so they never block the response. Accepts true/false, on/off, yes/no, 1/0; anything else throws an InvalidConfigurationException. |
| `tracking.user_agent` | PlausibleForLaravel | PLAUSIBLE\_TRACKING\_USER\_AGENT | User-agent for server-side captures when no HTTP request is in scope. |
| `tracking.ip_address` | 127.0.0.1 | PLAUSIBLE\_TRACKING\_IP | IP for server-side captures when no HTTP request is in scope. |
| `script.domain` | null | PLAUSIBLE\_SCRIPT\_DOMAIN | data-domain for the tracking script. Uses site when not set (null or blank). |
| `script.src` | https://plausible.io/js/script.js | PLAUSIBLE\_SCRIPT\_SRC | URL of the hosted Plausible script — your self-hosted host or a script variant. |

A missing url throws RoundlyConsulting\\Plausible\\Exceptions\\MissingConfiguration (a PlausibleException) on the first call, and a missing key on the first Stats or Sites call, rather than sending a broken request. Event capture works without a key. Calls that need a site throw the same exception when none is passed and no default is set.

Every other setting is read strictly. A key that is not set — left out, or blank such as PLAUSIBLE\_TIMEOUT= — takes the default above (a blank url, key or site counts as missing); a value of the wrong shape throws RoundlyConsulting\\PackageToolkit\\Exceptions\\InvalidConfigurationException naming the key, and is never cast or replaced by the default. Integers take an int or a whole-number string — PLAUSIBLE\_TIMEOUT=15 works, while five or 1.5 throw — and the user agent, IP address and script URL must be strings. The config file therefore passes env values through raw, with no (int) casts.

## API keys

Plausible issues two kinds of API key (Settings → API keys → New API key):

- a Stats API key — reads stats (stats()); Plausible limits it to 600 requests per hour by default, across every site the key’s team owns;
- a Sites API key — provisions sites, goals and shared links (sites(), goals(), sharedLinks()); the Sites API is an Enterprise plan feature.

The package sends the one configured PLAUSIBLE\_API\_KEY as a Bearer token to the Stats and Sites APIs, so use the key type for the APIs you call. The Events API — events(), the middleware and the Trackable trait — is unauthenticated: it needs only PLAUSIBLE\_URL, and the key is never sent there. php artisan plausible:health tells you whether the key works (see Health check).

## Environment

Every key except the rate-limit blocks maps to one env variable — the values below are the defaults where one exists:

```bash
PLAUSIBLE_URL=https://plausible.io
PLAUSIBLE_API_KEY=your-api-key
PLAUSIBLE_SITE=my-site.com
PLAUSIBLE_TIMEOUT=10
PLAUSIBLE_RETRY_TIMES=0
PLAUSIBLE_RETRY_SLEEP=100
PLAUSIBLE_TRACKING_QUEUE=true
PLAUSIBLE_TRACKING_USER_AGENT=PlausibleForLaravel
PLAUSIBLE_TRACKING_IP=127.0.0.1
PLAUSIBLE_SCRIPT_DOMAIN=my-site.com
PLAUSIBLE_SCRIPT_SRC=https://plausible.io/js/script.js
```

## The about command

The package contributes a Plausible section to php artisan about: the instance URL, whether the API key is SET or MISSING (the key itself is never printed), the default site, which surfaces are rate-limited, and whether tracking is queued.

```bash
php artisan about
```

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