Query API

Three read-only resources answer the three questions the dashboards answer. All share the same request shape and the same response shape.

How a Query Is Built#

Every request combines three kinds of parameter. Getting these three straight is most of what you need to know, because all three resources work the same way.

Think of it as a pivot table: dimensions are the row labels, metrics are the numeric columns. Request no dimensions and everything collapses into a single row — the total for the whole window, which is what a KPI tile needs. Request one or more and you get a row per combination, which is what a chart or table needs.

Response Shape#

Responses come wrapped in the standard dotCMS envelope. The query result is under entity:

{
  "entity": {
    "params":     { "from": "2026-08-06", "to": "2026-08-12", "project": "demo", … },
    "columns":    [ { "name": "day", "type": "DIMENSION" },
                    { "name": "totalEvents", "type": "METRIC" } ],
    "rows":       [ { "day": "2026-08-06", "totalEvents": 1240 } ],
    "totals":     { "totalEvents": 9423 },
    "pagination": { "page": 1, "pageSize": 20, "totalPages": 3, "totalItems": 60 }
  },
  "errors": [], "messages": [], "pagination": null, "permissions": []
}

Common Parameters#

*Send exactly one of from+to or range. Sending both, or half of one, returns 400.

Events#

Answers "how many times did this happen." The three metrics fall into two groups, and a metric's group decides which dimensions you may group it by:

Grouping by device or browser is only possible with pageviews; grouping by event type is only possible with the other two, since a page view is already a single event type.

Events is the only resource that accepts more than one dimension per request. You can also request several metrics at once, as long as every dimension you ask for is valid for all of them: metrics=totalEvents,uniqueVisitors&dimensions=day works, but metrics=totalEvents,pageviews&dimensions=device returns 400, because device pairs only with pageviews. The eventType filter is rejected outright alongside pageviews, which is already a single event type.

Example: Daily Trend#

curl -s "$BASE_URL/api/v1/analytics/events\
?range=last_14_days&metrics=totalEvents,uniqueVisitors&dimensions=day"

"entity": {
  "columns": [ { "name": "day", "type": "DIMENSION" },
               { "name": "totalEvents", "type": "METRIC" },
               { "name": "uniqueVisitors", "type": "METRIC" } ],
  "rows": [ { "day": "2026-07-25", "totalEvents": 3210, "uniqueVisitors": 1180 },
            { "day": "2026-07-26", "totalEvents": 3450, "uniqueVisitors": 1225 } ],
  "totals": { "totalEvents": 48213, "uniqueVisitors": 16720 }
}

Sessions#

Answers "how engaged are visitors." Eight metrics in two tiers — and the dimension you pick decides how many of them you can ask for:

The whole-window total and the day-by-day breakdown are the two detailed views; the other three are lighter and do not track the Extended metrics at all.

Sessions accepts at most one dimension, and there is no month bucket. Crossing the tiers — an Extended metric with device, browser or language — returns 400.

Omitting metrics follows the same split: all eight for a scalar query or grouped by day, the four Basic ones otherwise. Default sort order varies too — day ascends chronologically, device and browser ascend alphabetically, and language sorts by engagedSessions descending.

Example: Engagement by Device#

curl -s "$BASE_URL/api/v1/analytics/sessions?range=last_30_days&dimensions=device"

"rows": [
  { "device": "Desktop", "totalSessions": 5210, "engagedSessions": 3312,
    "engagementRate": 63.57, "avgEngagedSessionTimeSeconds": 248.1 },
  { "device": "Mobile",  "totalSessions": 3450, "engagedSessions": 1890,
    "engagementRate": 54.78, "avgEngagedSessionTimeSeconds": 198.4 }
]

Content#

Answers "which content performs best." One endpoint, two modes — and which one you get is inferred from the parameters you send rather than chosen explicitly.

Attribution is the richer view and the default, so you have to narrow deliberately to metrics=totalEvents — with none of the other triggers below — to get the simpler ranking instead.

attributionCount is the number of conversions the content preceded, and attributionRate is attributionCount / totalEvents × 100. Watch out for totalEvents: it means raw event volume in top-content mode but impressions that preceded a conversion in attribution mode — the same field name, two different numbers.

Omit dimensions and you get identifier,title in top-content mode, identifier,title,eventType in attribution mode.

conversionName restricts results to content that preceded that specific conversion, and selects attribution mode on its own. A request with no page/pageSize returns every matching row, which on a large catalogue can be hundreds — paginate.

Example: Conversion Drivers#

curl -s "$BASE_URL/api/v1/analytics/content\
?range=last_30_days&conversionName=form_submit&orderBy=attributionRate&orderDir=desc&pageSize=20"

"rows": [
  { "identifier": "abc-123", "title": "Spring Sale Landing Page", "eventType": "pageview",
    "totalEvents": 4210, "attributionCount": 512, "attributionRate": 12.16 },
  { "identifier": "def-456", "title": "Product Launch Blog Post", "eventType": "pageview",
    "totalEvents": 3185, "attributionCount": 201, "attributionRate": 6.31 }
]

Errors#