Aggregate analytics events by field

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Breaks the app's analytics events down by the value of a field, so you can rank them: the busiest pages, the countries your users come from, the most tracked event names.

Every metric must set field, and that field is what the metric groups by. user_id, session_id, event_id, event_name and page_url group by those top-level fields, which is what the default metric does. A metadata. prefix groups by the device information Base44 captures itself: metadata.country, metadata.device_type, and metadata.os. Any other name groups by an event property. Groups come back largest first, capped at max_groups per metric. The range defaults to the last 30 days, and events are kept for 60 days.

Use count for the metric function. Because a metric's field is both the field it groups by and the field its function reads, the other functions return a value the grouping already implies: count_unique reports 1 for every group, and sum, avg, min, max and the percentiles report the group's own value.

Each entry in groups carries exactly one metric. When you send several metrics, the list holds one entry per group value per metric, so read the metric name off each entry's metrics key instead of assuming a single set of groups. group_count counts those entries across all metrics, not the number of distinct group values.

<Note>This endpoint takes no filter expression. To break down a filtered set of events, filter by event name here, or use Aggregate analytics events over time with q and a single bucket.</Note>

{
  "event_name": "checkout_completed",
  "start_time": "2026-07-03T00:00:00Z",
  "end_time": "2026-08-02T00:00:00Z",
  "max_groups": 10,
  "metrics": [
    {
      "field": "page_url",
      "function": "count",
      "name": "event_count"
    }
  ]
}

{
  "event_name": "checkout_completed",
  "group_count": 10,
  "totals": {
    "event_count": 3840
  },
  "groups": [
    {
      "group": "/checkout",
      "metrics": {
        "event_count": 842
      }
    },
    {
      "group": "/pricing",
      "metrics": {
        "event_count": 517
      }
    }
  ]
}