Configuration

All settings live at Settings → Plugins → Telescope.

Setting	Default	Notes
Authentication method	Service account	Or OAuth refresh token. See Connecting to GA4.
Service account credentials	—	The JSON key, a path to the key file, or an env var holding either.
GA4 property ID	—	Numeric, from Admin → Property details. Not the `G-XXXXXXX` measurement ID.
Per-site property IDs	—	Overrides the default property, keyed by site handle. See Multi-site.
Filter by hostname	Off	Turn on when several Craft sites report into one GA4 property.
Default period	Last 28 days	Also accepts a raw GA4 date such as `90daysAgo` or `2026-01-01`.
Path match type	Exact	Or begins with / contains, for section-wide roll-ups.
Include query strings	Off	Off means `/blog?page=2` counts towards `/blog`.
Report sections	All six	Each section is one API call — switch off what you don’t need.
Table rows	10	Rows in each breakdown table (1–100).
Cache duration	600s	Reports are cached; the Data API is rate limited. Up to 7 days.
Show on all entries	Off	Adds the compact sidebar panel without any field layout changes.
Limited to sections	All	Restricts the sidebar panel to chosen Craft sections. Empty means all of them.
Widget rows	10	Pages listed in the dashboard widget (1–50).

Path matching

Telescope reports on the page path of an element’s URL. https://example.com/about/ becomes /about: the trailing slash is trimmed and the query string dropped, because a GA4 exact match on /about/ will not find hits recorded against /about.

Path match type changes that behaviour:

Exact — only that page. The right choice almost always.
Begins with — the page and everything beneath it. Use it on a section index entry to roll up the whole section: /blog then covers /blog/some-post too.
Contains — anything with the path as a substring. Broad; useful when your URLs carry a prefix that GA4 records inconsistently.

Include query strings keeps the query on the path when matching, so /blog?page=2 is counted separately from /blog instead of being folded into it.

Report sections

Six sections can be enabled independently: overview, timeline, geography, sources, referrers and landing pages. Each one is a separate Data API call, so a full report costs six — the fastest way to cut quota use is to switch off sections nobody reads.

Caching

Reports are cached for Cache duration seconds, ten minutes by default. Set it to 0 to disable caching entirely, though on any site with real editors that will make the Data API rate limit your problem.

Failed calls are never cached. Fixing a credential problem takes effect on the next page load rather than after the cache expires.

To clear cached reports by hand, see telescope/analytics/clear-cache.

Environment variables

Every credential-bearing setting is read through Craft’s env parsing, so you can store the value in .env and enter $VARIABLE_NAME in the setting. That keeps private keys out of committed project config — see Connecting to GA4.

Next: Multi-site