How do I query AI referral statistics with Plausible's API?

Definition: As of October 2026, Plausible's Stats API retrieves AI referral statistics through a read-only request filtered by visit:channel or visit:source. Filtering the AI Assistants channel and grouping by visit:source returns a breakdown of traffic attributed to known AI assistant sources.

Key facts

• Plausible's Stats API reference documents JSON queries sent by POST to /api/v2/query.
• Plausible's traffic sources documentation defines AI Assistants as traffic whose source is a known assistant tool, including ChatGPT and Claude.
• Plausible's metrics definitions count the same person on different days or devices as separate unique visitors.

What does the request require?

Plausible's Stats API reference requires site_id, date_range and metrics. The site identifier is the domain as added to Plausible. Authentication uses an API key in an Authorization: Bearer header; Stats API access is a Business plan feature. The default rate limit is 600 requests per hour.

The example below adapts the documented request structure. dummy.site and YOUR-KEY are placeholders. The 7d range covers the last seven days relative to today. visitors measures unique visitors, while visits measures sessions.

How does a channel filter return a source breakdown?

In the API query structure, a filter limits the events or sessions included, and a dimension is an attribute used to group the results. This request filters by channel and groups by source, ordered by visitors descending:

curl --request POST \
  --url 'https://plausible.io/api/v2/query' \
  --header 'Authorization: Bearer YOUR-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "site_id": "dummy.site",
    "date_range": "7d",
    "metrics": ["visitors", "visits"],
    "filters": [["is", "visit:channel", ["AI Assistants"]]],
    "dimensions": ["visit:source"],
    "order_by": [["visitors", "desc"]]
  }'

Each response row contains a dimensions array and a metrics array. Their values follow the order requested: the source label appears in dimensions, and the visitor and session counts appear in metrics.

How does a source filter change the query?

Plausible's traffic sources documentation lists chatgpt.com as an example source. A source-specific request uses the exact source label returned by the breakdown. For that label, the following body groups sessions by their landing page:

{
  "site_id": "dummy.site",
  "date_range": "7d",
  "metrics": ["visitors", "visits"],
  "filters": [["is", "visit:source", ["chatgpt.com"]]],
  "dimensions": ["visit:entry_page"],
  "order_by": [["visitors", "desc"]]
}

The Stats API reference defines visit:entry_page as the page where the session starts. It defines visit:source as populated from a URL parameter such as utm_source, source or ref, or from the HTTP Referer header. visit:utm_source specifically contains the raw utm_source parameter on the entry page.

A single is filter accepts multiple source labels in its value list and matches any of them. Separate top-level filters are combined with an implicit and; adding both a channel filter and a source filter requires both conditions to match.

How are totals and daily results requested?

Plausible's dimensions documentation makes dimensions optional, with an empty array as its default. Keeping the filter and using "dimensions": [] requests an aggregate. Using "dimensions": ["time:day"] groups the filtered traffic by day in the site's reporting timezone. Time dimensions belong in dimensions; date_range sets the period.

Related terms

• AI referral traffic
• Where does Plausible show AI assistant traffic?
• How do I find entry pages used by AI referrals in Plausible?
• How do UTM parameters affect Plausible's referral classification?

FAQ

Can I include several assistant sources in one query?

Yes. The Stats API filter syntax accepts a list of values in an is filter. You can retain visit:source as a dimension to receive separate rows for each matching source.

Does the AI channel capture every visit from an assistant?

Plausible's traffic sources documentation describes missing referrer information as a cause of Direct / None traffic. You cannot infer a complete count of assistant-origin visits from the AI Assistants channel alone.

Sources

1. Plausible, "Plausible Stats API reference", 29 September 2026
2. Plausible, "Traffic sources, referrers and UTM campaigns", 15 October 2026
3. Plausible, "Metrics definitions", 24 September 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer