Twig API

Everything the control panel shows is available to your templates through craft.telescope.* — including the chart renderer and the formatters, so front-end output can match the control panel exactly.

A quick example

{% set report = craft.telescope.report(entry) %}

{{ report.overview.views|number_format }} views
{{ craft.telescope.duration(report.overview.averageSessionDuration) }} average session
{{ craft.telescope.percent(report.overview.engagementRate) }} engaged

{{ craft.telescope.chart(report.timeline)|raw }}

{% for page in craft.telescope.topPages(null, 'last7days', 5) %}
    {{ page.title }} — {{ page.views }}
{% endfor %}

Reports

`report(element, period = null)`

The report for an element. period is a preset handle such as last7days, or a raw GA4 date; omit it to use the configured default.

`reportForUrl(url, siteId = null, period = null)`

The report for an arbitrary URL or path — useful for pages that are not entries.

Both return a PageReport with these properties:

Property	What it holds
`overview`	Views, visitors, sessions, average session duration, engagement rate, bounce rate
`timeline`	A list of `{ date, views, users }` points
`geography`	Visitors by country
`sources`	Sessions by source / medium
`referrers`	Sessions by referring page
`landingPages`	Sessions by landing page
`errors`	Any per-section failures, so a partial report still renders

Sections you have switched off in the settings come back empty. Neither method throws: if the plugin is not configured or a call fails, you get an empty report and the reason in errors.

Top pages

`topPages(siteId = null, period = null, limit = null)`

The property’s most-viewed pages, as a list of { path, title, views, users }. limit defaults to the Widget rows setting.

Helpers

Call	Returns
`chart(timeline, width = 960, height = 240)`	The timeline as inline SVG — two series, page views and visitors, in the same colours the control panel uses. Output it with `\|raw`. An empty timeline returns an empty string.
`duration(seconds)`	A readable duration, e.g. `2m 14s`
`percent(ratio, decimals = 1)`	A ratio as a percentage, e.g. `61.4%`
`compact(value)`	A large number shortened, e.g. `24.2K`
`periods()`	The preset period handles mapped to their labels — for building your own dropdown
`isConfigured()`	Whether credentials and a property ID are present. Worth checking before rendering an analytics block.

A note on caching

Front-end calls go through the same cache as the control panel, so a template that renders a report on every request costs one set of API calls per cache period, not per visitor. Even so, be wary of calling report() inside a loop over many entries — that is one report each, and each report is up to six Data API calls the first time round.

Guarding output

{% if craft.telescope.isConfigured() %}
    {% set report = craft.telescope.report(entry) %}
    {% if report.overview.views %}
        Read {{ craft.telescope.compact(report.overview.views) }} times.
    {% endif %}
{% endif %}

Next: Troubleshooting