Dimensions and metrics

A dimension is what a row of a report is about (a page, a country, a traffic source), a metric is what is counted for it (page views, sessions, bounce rate). In the API you use their names:

  • dimensions in primaryProp, customCols, select, dimensionsFilters and sort, and in the path of /acquisition/{dimension}
  • metrics in metricsCols, metricsFilters and sort

What each term means is explained in the Glossary. This page lists the standard dimensions and metrics, the same for every site. A site can also have custom dimensions and custom metrics: they are used in exactly the same way, with the name you gave them.

The complete list for a site: GET /meta

GET /site/{siteId}/meta returns every dimension and metric a site accepts, standard and custom together, with "custom": true on the custom ones, the datasets each one belongs to and the filter operators each dimension accepts. It also leaves out the dimensions the plan of the site does not include. Since it reflects the site's own configuration, it is the list to rely on when building a query.

curl 'https://publytics.net/api/site/{siteId}/meta' \
  --header 'Authorization: Bearer {token}'

Datasets

Every endpoint reads one of four datasets, and accepts only the dimensions and metrics of that dataset.

Dataset What it counts Endpoints
content Page views, each one on the page where it happened /content, /acquisition/entry, /acquisition/exit
audience Sessions, each one with how it started: source, entry page, device, country... /acquisition/{dimension}, /visitors, /visitors/{dimension}, /ai-traffic
events Custom events /events
realtime Page views of the last 30 minutes /realtime/overview

Standard dimensions

Unless noted, a dimension belongs to all four datasets.

Name Label Type Description
pathname Pathname text The path of the page, after the domain: in example.com/blog/article it is /blog/article.
hostname Hostname text The domain of the page, like example.com.
entry_pathname Entry Page text The first page of the session.
exit_pathname Exit Page text The last page of the session. Not in realtime. Needs the Exits enhancement.
pagepath_level1 … pagepath_level5 Pagepath Level 1 … 5 text The first five levels of the path, e.g. /blog/ and /blog/2026/, to group pages by section.
referrer Referrer text The domain of the page that brought the visitor, e.g. google.com or lm.facebook.com; empty when there is none.
referrer_source Referrer + Source text The friendly name of the referrer, or the utm_source when present, e.g. Google, Facebook, chatgpt.com. Empty when there is none (filter it with EMPTY).
source_medium Source / Medium text utm_source and utm_medium together, e.g. newsletter / email.
utm_source UTM Source text The utm_source parameter of the landing URL.
utm_medium UTM Medium text The utm_medium parameter.
utm_campaign UTM Campaign text The utm_campaign parameter.
utm_content UTM Content text The utm_content parameter.
utm_term UTM Term text The utm_term parameter.
country_code Country fixed list The visitor's country, from the IP address, as an ISO 3166-1 alpha-2 code (IT, US...); empty when unknown.
region Region text The visitor's region. Needs the City enhancement.
city City text The visitor's city. Needs the City enhancement.
screen_size Device fixed list Desktop, Mobile or Tablet (empty when unknown).
browser Browser text E.g. Chrome, Safari, Firefox.
browser_version Browser Version text Needs the OS/Browser Versions enhancement.
operating_system Operating System text E.g. Windows, iOS, Android.
operating_system_version Operating System Version text Needs the OS/Browser Versions enhancement.
date Date date The day, YYYY-MM-DD.
year Year number The year, e.g. 2026.
month Month fixed list The month of the year, from 1 (January) to 12.
day_name Day Name fixed list The day of the week, from 1 (Monday) to 7 (Sunday).
hourminute Hour + Minute time The time of day, HH:MM. Hour and minute detail need the Hour and Minute enhancements.
datetime Datetime datetime Day and time, returned as YYYY-MM-DD HH:MM and filtered as YYYY-MM-DD HH:MM:SS.
name Event Name text The name of the custom event. Only in events and realtime.
site_id Site Domain fixed list The domain of the site, only on networks: filter it with the domain, e.g. example.com.

The fixed list dimensions accept only their listed values, with the operators = and !=; /meta lists the values of each one.

Standard metrics

Some metrics have a different label in each dataset, as in the dashboard tables. Metrics belong only to the datasets that have a label for them; the realtime dataset has its own metrics, described in Get Realtime Overview.

Name content audience events Description
views Pageviews Pageviews Hits The page views (or, for events, how many times the event happened).
sessions Involved Sessions Session Hits The sessions that viewed the page, or performed the event.
viewers Unique Pageviews Unique Hits The visitors who viewed the page, or performed the event. ¹
entrances Entrances Sessions The sessions that started on the page; in audience, the sessions.
unique_entrances Unique Entrances Users The visitors who started a session on the page; in audience, the visitors. ¹
exits Exits Exits The sessions that ended on the page.
unique_exits Unique Exits Unique Exits The visitors who ended a session on the page. ¹
bounce_rate Bounce Rate (Entrances) Bounce Rate The share of the sessions that started here and bounced (see Bounce Rate). ²
bounce_rate_sessions Bounce Rate The share of the sessions that viewed the page and bounced. ²
avg_time Avg. Session Duration (Entrances) Avg. Session Duration The average duration of the sessions that started here, in seconds.
avg_time_sessions Avg. Session Duration The average duration of all the sessions that viewed the page, in seconds.
avg_time_on_page Avg. Time on Page Avg. Time on Page The average time on the page, in seconds.
views_per_session Pageviews per Sessions Hits per Session Hits views / sessions.
sessions_per_user Sessions per Users Session Hits per Unique Hits sessions / viewers.
views_per_entrance Pageviews per Entrances Pageviews per Sessions views / entrances.
entrances_per_user Entrances per Unique Entrances Sessions per Users entrances / unique_entrances.
quality_views Quality Pageviews Quality Pageviews The page views with at least 15 seconds of engagement time. ³
quality_views_perc % Quality Pageviews % Quality Pageviews quality_views / views. ² ³
avg_engagement_time Avg. Engagement Time Avg. Engagement Time The average time the visitor actively engaged with the page, in seconds. ³
scroll_depth Scroll Depth Scroll Depth How far down the page the visitor scrolled (the deepest point reached, as a share of the page height), averaged over the page views. ² ³

¹ Daily unique counts. They are computed per day: over a period of more days they are the sum of the daily values, so a returning visitor is counted once per day. Summed over several rows (pages, sources) a visitor is also counted once per row.

² Shares are fractions between 0 and 1: a bounce rate of 47.3% is returned as 0.473, and is filtered the same way (["bounce_rate", "<", 0.5]).

³ Needs engagement tracking (the Engagement Time enhancement); without it the metric is 0.

Default metrics

When metricsCols is omitted, every endpoint returns its own default metrics:

Endpoint Default metrics
/content views, sessions, viewers, avg_time_on_page, bounce_rate_sessions
/acquisition/entry entrances, unique_entrances, bounce_rate
/acquisition/exit exits, unique_exits
/acquisition/{dimension}, /visitors/{dimension} views, entrances, unique_entrances, avg_time, bounce_rate
/events views, sessions, viewers
/ai-traffic views, entrances, unique_entrances (fixed)
Previous

Endpoint List
Next

MCP server: Connect an AI assistant