Aggregate analytics events by field

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/analytics/grouped \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "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"
    }
  ]
}
'

import requests

url = "https://app.base44.com/api/apps/{app_id}/analytics/grouped"

payload = {
    "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"
        }
    ]
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/analytics/grouped', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/apps/{app_id}/analytics/grouped",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/apps/{app_id}/analytics/grouped"

	payload := strings.NewReader("{\n  \"event_name\": \"checkout_completed\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"max_groups\": 10,\n  \"metrics\": [\n    {\n      \"field\": \"page_url\",\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/apps/{app_id}/analytics/grouped")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event_name\": \"checkout_completed\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"max_groups\": 10,\n  \"metrics\": [\n    {\n      \"field\": \"page_url\",\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/apps/{app_id}/analytics/grouped")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event_name\": \"checkout_completed\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"max_groups\": 10,\n  \"metrics\": [\n    {\n      \"field\": \"page_url\",\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

Aggregate analytics events by field

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

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.

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.

POST

api

apps

{app_id}

analytics

grouped

Aggregate analytics events by field

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/analytics/grouped \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "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"
    }
  ]
}
'

import requests

url = "https://app.base44.com/api/apps/{app_id}/analytics/grouped"

payload = {
    "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"
        }
    ]
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/analytics/grouped', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/apps/{app_id}/analytics/grouped",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/apps/{app_id}/analytics/grouped"

	payload := strings.NewReader("{\n  \"event_name\": \"checkout_completed\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"max_groups\": 10,\n  \"metrics\": [\n    {\n      \"field\": \"page_url\",\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/apps/{app_id}/analytics/grouped")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event_name\": \"checkout_completed\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"max_groups\": 10,\n  \"metrics\": [\n    {\n      \"field\": \"page_url\",\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/apps/{app_id}/analytics/grouped")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event_name\": \"checkout_completed\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"max_groups\": 10,\n  \"metrics\": [\n    {\n      \"field\": \"page_url\",\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

api_key

string

header

required

Personal API key.

Path Parameters

app_id

string

required

ID of the app whose analytics to read.

Body

application/json

Request for grouped event aggregation.

event_name

string | null

Name of the event to aggregate. Omit to aggregate every event the app tracks.

Example:

"checkout_completed"

start_time

string<date-time> | null

Start of the time range. Defaults to 30 days ago.

Example:

"2026-07-03T00:00:00Z"

end_time

string<date-time> | null

End of the time range. Defaults to now.

Example:

"2026-08-02T00:00:00Z"

max_groups

integer

default:100

Maximum number of groups to return per metric, between 1 and 1000. The largest groups are kept.

Required range: 1 <= x <= 1000

Example:

10

metrics

AggregationMetric · object[]

Between 1 and 10 metrics to compute. Each one must set field, which is the field it groups by. Defaults to an event count per event name, named event_count.

Required array length: 1 - 10 elements

Show child attributes

Example:

[
  {
    "field": "page_url",
    "function": "count",
    "name": "event_count"
  }
]

Response

The grouped metrics.

Response for grouped event aggregation.

event_name

string | null

The event name that was aggregated, or null when the request covered every event.

Example:

"checkout_completed"

group_count

integer

default:0

Number of entries in groups, summed across every metric.

Example:

10

totals

Totals · object

Each metric computed over the whole range without grouping, keyed by metric name.

Show child attributes

Example:

{ "event_count": 3840 }

groups

AggregationGroup · object[]

One entry per group value per metric, largest metric value first within each metric.

Show child attributes

Example:

[
  {
    "group": "/checkout",
    "metrics": { "event_count": 842 }
  },
  {
    "group": "/pricing",
    "metrics": { "event_count": 517 }
  }
]

⌘I

App Management API (Beta)

Entities API (Beta)

Virality API (Beta)

Analytics API (Beta)

Monitoring API

Audit Logs API

Aggregate analytics events by field

Authorizations

Path Parameters

Body

Response