A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Plausible API is how an app or AI agent works with a Plausible account: querying a site's visitors and conversions, creating or deleting a site, managing its goals and shared links, or recording a pageview from a server. Access is granted through a Bearer API key, where a Stats key reads analytics and a separate Sites key provisions and manages sites, so the key type sets the boundary. Plausible does not push events; an integration polls the stats it needs.
How an app or AI agent connects to Plausible determines what it can reach. There is a route for reading stats, a route for managing sites, and a route for sending events, and each is governed by the key behind it and the type of access that key carries.
The Stats API reads historical and real-time analytics. The current v2 query endpoint takes a JSON body naming a site, a date range, and the metrics to return, with optional dimensions, filters, and ordering, so one request can be an aggregate, a time series, or a breakdown. A Stats API key authenticates each call with the Bearer method.
The Sites Provisioning API creates, lists, updates, and deletes sites, and manages their goals, shared links, and custom properties. It is authenticated with a separate Sites API key using the Bearer method, and a modern key is scoped to a specific team. The Sites API is an Enterprise plan feature.
The Events API records pageviews and custom events from places the tracking script cannot run, like a mobile app or a server. It needs no API key; the request carries a User-Agent header used to derive the visitor and a body naming the site domain, the event, and the page URL, and an X-Forwarded-For header sets the real client IP for server-side calls.
A Stats API key authenticates read calls to the Stats API, sent as a Bearer token. It is created in account settings by choosing Stats API from the key type. It reads analytics for the account's sites and cannot provision or change sites.
A Sites API key authenticates calls to the Sites Provisioning API, sent as a Bearer token. It is created by choosing Sites API from the key type, and a modern key is scoped to a specific team so it only acts on that team's sites. It is needed to create, update, or delete sites, goals, shared links, and custom properties.
The Events API takes no API key. A request is accepted on the strength of the site domain in its body, with a User-Agent header to identify the visitor. Because anyone can post to it, it is an ingestion endpoint rather than an authenticated one.
The Plausible API splits into reading stats, provisioning sites, and ingesting events. Reading stats answers questions about traffic and conversions, while provisioning a site, a goal, or a shared link changes the account itself, and sending an event records new analytics data.
Methods for reading historical and real-time analytics with the v2 query endpoint.
The older v1 stats endpoints, kept available for existing integrations.
Methods for creating, listing, updating, and deleting sites in an account.
Methods for managing the goals a site converts on.
Methods for creating shareable dashboard links for a site.
Methods for managing the custom event properties a site collects.
The endpoint for recording pageviews and custom events from apps and servers.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Stats (query)Methods for reading historical and real-time analytics with the v2 query endpoint.1 | ||||||
| POST | /api/v2/query | Run a stats query against a site, returning aggregate, time series, or breakdown results. | read | Stats key | Current | |
Read-only. Takes a JSON body with site_id, date_range, metrics, and optional dimensions, filters, and order_by. The Stats API is a Business plan feature. Acts onstats_query Permission (capability) Stats keyVersionIntroduced 2024-10-09 Webhook eventNone Rate limit600 requests per hour per key SourceOfficial documentation ↗ | ||||||
Stats (legacy v1)The older v1 stats endpoints, kept available for existing integrations.4 | ||||||
| GET | /api/v1/stats/aggregate | Return aggregate metrics for a site over a period (legacy v1 interface). | read | Stats key | Deprecated | |
Read-only. Superseded by the v2 query endpoint, which Plausible recommends for new integrations. Acts onstats_aggregate Permission (capability) Stats keyVersionDeprecated 2024-10-09 Webhook eventNone Rate limit600 requests per hour per key SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/stats/timeseries | Return a time series of a metric over a period (legacy v1 interface). | read | Stats key | Deprecated | |
Read-only. Superseded by the v2 query endpoint. Acts onstats_timeseries Permission (capability) Stats keyVersionDeprecated 2024-10-09 Webhook eventNone Rate limit600 requests per hour per key SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/stats/breakdown | Break a metric down by a property such as page, source, or country (legacy v1 interface). | read | Stats key | Deprecated | |
Read-only. Superseded by the v2 query endpoint's dimensions. Acts onstats_breakdown Permission (capability) Stats keyVersionDeprecated 2024-10-09 Webhook eventNone Rate limit600 requests per hour per key SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/stats/realtime/visitors | Return the number of current visitors on a site (legacy v1 interface). | read | Stats key | Deprecated | |
Read-only. A current visitor is one active in the last 5 minutes. Acts onstats_realtime Permission (capability) Stats keyVersionDeprecated 2024-10-09 Webhook eventNone Rate limit600 requests per hour per key SourceOfficial documentation ↗ | ||||||
SitesMethods for creating, listing, updating, and deleting sites in an account.6 | ||||||
| GET | /api/v1/sites | List the sites in the account, optionally scoped to a team. | read | Sites key | Current | |
Read-only. Accepts an optional team_id to scope results to one team. The Sites API is an Enterprise plan feature. Acts onsite Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/sites | Create a new site in the account. | write | Sites key | Current | |
Takes domain, with optional timezone, team_id, and tracker_script_configuration. Acts onsite Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/sites/:site_id | Retrieve the details of one site. | read | Sites key | Current | |
Read-only. The site_id is the site domain as added to Plausible. Acts onsite Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/sites/:site_id | Update a site, such as changing its domain or tracker configuration. | write | Sites key | Current | |
Takes optional domain and tracker_script_configuration. Acts onsite Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/sites/:site_id | Permanently delete a site and its data from the account. | write | Sites key | Current | |
Irreversible; removes the site and the stats collected under it. Acts onsite Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/sites/teams | List the teams the key can act on. | read | Sites key | Current | |
Read-only. A modern key is scoped to a specific team and only sees sites in that team. Acts onteam Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GoalsMethods for managing the goals a site converts on.3 | ||||||
| GET | /api/v1/sites/goals | List the goals configured on a site. | read | Sites key | Current | |
Read-only. Scoped to one site by site_id. Acts ongoal Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/sites/goals | Create or find a goal on a site, as an event goal or a page-path goal. | write | Sites key | Current | |
Takes site_id and goal_type (event or page), plus event_name or page_path, with optional display_name. Acts ongoal Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/sites/goals/:goal_id | Delete a goal from a site. | write | Sites key | Current | |
Removes the goal; the site stops counting it as a conversion. Acts ongoal Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Shared linksMethods for creating shareable dashboard links for a site.1 | ||||||
| PUT | /api/v1/sites/shared-links | Create or find a shared link that exposes a site's dashboard. | write | Sites key | Current | |
Takes site_id and name; returns a URL that grants dashboard access to anyone who holds it. Acts onshared_link Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom propertiesMethods for managing the custom event properties a site collects.3 | ||||||
| GET | /api/v1/sites/custom-props | List the custom event properties a site collects. | read | Sites key | Current | |
Read-only. Scoped to one site by site_id. Acts oncustom_property Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/sites/custom-props | Add a custom event property to a site so it appears in the dashboard. | write | Sites key | Current | |
Takes site_id and the property to enable. Acts oncustom_property Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/sites/custom-props/:property | Remove a custom event property from a site. | write | Sites key | Current | |
Stops the property showing in the dashboard; past data is retained. Acts oncustom_property Permission (capability) Sites keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Events (ingestion)The endpoint for recording pageviews and custom events from apps and servers.1 | ||||||
| POST | /api/event | Record a pageview or a custom event against a site, for mobile apps or server-side tracking. | write | — | Current | |
Public ingestion; needs no API key. Requires a User-Agent header and a body with domain, name, and url, with optional referrer, props, and revenue. Acts onevent Permission (capability)None required VersionIntroduced 2021-09-08 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Plausible does not push events to an integration. To learn about new activity, an app polls the Stats API on its own schedule rather than receiving a callback.
| Event | What it signals | Triggered by |
|---|
Plausible meters how fast a key can call the API, capping requests per hour, and pages large stats results with a row limit and an offset.
Plausible meters the Stats API by request rate per key, allowing 600 requests per hour by default; higher capacity is available by contacting Plausible. There is no per-method point cost. The Events API is a public ingestion endpoint and is not authenticated with a key.
A Stats API v2 query pages results with a pagination object, defaulting to a limit of 10,000 rows and an offset of 0. An integration raises the offset to walk through a result set larger than one page.
A single stats query returns at most its pagination limit of rows, 10,000 by default. An Events API request carries at most 30 custom property key-value pairs per event.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid API key was provided, or the key was sent incorrectly. | Send a valid key as a Bearer token in the Authorization header, and confirm it is the right key type for the endpoint. |
| 429 | too_many_requests | The key went over its hourly request limit, 600 requests per hour by default. | Slow the request rate and retry later, or contact Plausible to raise the limit. |
Plausible versions its stats interface by a path segment, currently the v2 query endpoint, and keeps the older v1 stats endpoint available for existing integrations.
The v2 query endpoint replaced the separate v1 aggregate, timeseries, and breakdown endpoints with a single endpoint that takes a JSON body. It added multiple dimension breakdowns, custom result ordering, new location dimensions, regex matching, and OR/AND/NOT filter conditions, with better performance on large datasets.
Plausible released the Events API to record pageviews and custom events from places the tracking script cannot run, like mobile apps and server-side code, alongside the existing Stats and Sites APIs.
Build new integrations on the v2 query endpoint; the v1 stats endpoint remains for older code.
Plausible changelog ↗Bollard AI sits between a team's AI agents and Plausible. Grant each agent exactly the access it needs, reading stats without ever managing sites, and every call is checked and logged.