Aggregate analytics events over time

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/analytics/timeseries \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "event_name": "checkout_completed",
  "q": "{\"metadata.country\": \"US\"}",
  "start_time": "2026-07-03T00:00:00Z",
  "end_time": "2026-08-02T00:00:00Z",
  "bucket_size_ms": 86400000,
  "max_buckets": 100,
  "metrics": [
    {
      "function": "count",
      "name": "event_count"
    },
    {
      "field": "user_id",
      "function": "count_unique",
      "name": "unique_users"
    }
  ]
}
'

import requests

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

payload = {
    "event_name": "checkout_completed",
    "q": "{\"metadata.country\": \"US\"}",
    "start_time": "2026-07-03T00:00:00Z",
    "end_time": "2026-08-02T00:00:00Z",
    "bucket_size_ms": 86400000,
    "max_buckets": 100,
    "metrics": [
        {
            "function": "count",
            "name": "event_count"
        },
        {
            "field": "user_id",
            "function": "count_unique",
            "name": "unique_users"
        }
    ]
}
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',
    q: '{"metadata.country": "US"}',
    start_time: '2026-07-03T00:00:00Z',
    end_time: '2026-08-02T00:00:00Z',
    bucket_size_ms: 86400000,
    max_buckets: 100,
    metrics: [
      {function: 'count', name: 'event_count'},
      {field: 'user_id', function: 'count_unique', name: 'unique_users'}
    ]
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/analytics/timeseries', 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/timeseries",
  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',
    'q' => '{"metadata.country": "US"}',
    'start_time' => '2026-07-03T00:00:00Z',
    'end_time' => '2026-08-02T00:00:00Z',
    'bucket_size_ms' => 86400000,
    'max_buckets' => 100,
    'metrics' => [
        [
                'function' => 'count',
                'name' => 'event_count'
        ],
        [
                'field' => 'user_id',
                'function' => 'count_unique',
                'name' => 'unique_users'
        ]
    ]
  ]),
  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/timeseries"

	payload := strings.NewReader("{\n  \"event_name\": \"checkout_completed\",\n  \"q\": \"{\\\"metadata.country\\\": \\\"US\\\"}\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"bucket_size_ms\": 86400000,\n  \"max_buckets\": 100,\n  \"metrics\": [\n    {\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    },\n    {\n      \"field\": \"user_id\",\n      \"function\": \"count_unique\",\n      \"name\": \"unique_users\"\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/timeseries")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event_name\": \"checkout_completed\",\n  \"q\": \"{\\\"metadata.country\\\": \\\"US\\\"}\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"bucket_size_ms\": 86400000,\n  \"max_buckets\": 100,\n  \"metrics\": [\n    {\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    },\n    {\n      \"field\": \"user_id\",\n      \"function\": \"count_unique\",\n      \"name\": \"unique_users\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"q\": \"{\\\"metadata.country\\\": \\\"US\\\"}\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"bucket_size_ms\": 86400000,\n  \"max_buckets\": 100,\n  \"metrics\": [\n    {\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    },\n    {\n      \"field\": \"user_id\",\n      \"function\": \"count_unique\",\n      \"name\": \"unique_users\"\n    }\n  ]\n}"

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

{
  "bucket_interval": 86400000,
  "bucket_count": 30,
  "event_name": "checkout_completed",
  "totals": {
    "event_count": 3840,
    "unique_users": 612
  },
  "buckets": [
    {
      "bucket": "2026-08-01",
      "metrics": {
        "event_count": 112,
        "unique_users": 47
      }
    },
    {
      "bucket": "2026-08-02",
      "metrics": {
        "event_count": 128,
        "unique_users": 54
      }
    }
  ]
}

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

API Reference

Aggregate analytics events over time

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

Aggregates the app’s analytics events into time buckets, so you can chart them. Send the metrics you want per bucket, and Base44 returns them per bucket plus a total over the whole range.

The range defaults to the last 30 days. Events are kept for 60 days, so an older range returns nothing. timestamp bounds inside q override start_time and end_time.

Base44 buckets by one of a fixed set of intervals: 1, 2, 3, 4, 6, 8 and 12 hours, 1, 2 and 3 days, 1 and 2 weeks, and 30 days. One hour is the finest available. Omit bucket_size_ms to get the finest interval that keeps the bucket count within max_buckets. Pass it to choose an interval yourself: Base44 rounds it down to the nearest supported interval, and rounds it up to one hour when you ask for anything finer, so a sub-hour request comes back coarser than you asked. Read the interval it used off bucket_interval in the response rather than assuming your request was honored. Keep bucket_size_ms coarse enough that the range divides into no more than max_buckets buckets.

Buckets with no matching events are left out, so chart your own zero for the gaps. count and count_unique work on any field, while sum, avg, min, max and the percentiles read the field as a number and report 0 for a bucket whose values are all non-numeric.

POST

api

apps

{app_id}

analytics

timeseries

Aggregate analytics events over time

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/analytics/timeseries \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "event_name": "checkout_completed",
  "q": "{\"metadata.country\": \"US\"}",
  "start_time": "2026-07-03T00:00:00Z",
  "end_time": "2026-08-02T00:00:00Z",
  "bucket_size_ms": 86400000,
  "max_buckets": 100,
  "metrics": [
    {
      "function": "count",
      "name": "event_count"
    },
    {
      "field": "user_id",
      "function": "count_unique",
      "name": "unique_users"
    }
  ]
}
'

import requests

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

payload = {
    "event_name": "checkout_completed",
    "q": "{\"metadata.country\": \"US\"}",
    "start_time": "2026-07-03T00:00:00Z",
    "end_time": "2026-08-02T00:00:00Z",
    "bucket_size_ms": 86400000,
    "max_buckets": 100,
    "metrics": [
        {
            "function": "count",
            "name": "event_count"
        },
        {
            "field": "user_id",
            "function": "count_unique",
            "name": "unique_users"
        }
    ]
}
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',
    q: '{"metadata.country": "US"}',
    start_time: '2026-07-03T00:00:00Z',
    end_time: '2026-08-02T00:00:00Z',
    bucket_size_ms: 86400000,
    max_buckets: 100,
    metrics: [
      {function: 'count', name: 'event_count'},
      {field: 'user_id', function: 'count_unique', name: 'unique_users'}
    ]
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/analytics/timeseries', 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/timeseries",
  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',
    'q' => '{"metadata.country": "US"}',
    'start_time' => '2026-07-03T00:00:00Z',
    'end_time' => '2026-08-02T00:00:00Z',
    'bucket_size_ms' => 86400000,
    'max_buckets' => 100,
    'metrics' => [
        [
                'function' => 'count',
                'name' => 'event_count'
        ],
        [
                'field' => 'user_id',
                'function' => 'count_unique',
                'name' => 'unique_users'
        ]
    ]
  ]),
  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/timeseries"

	payload := strings.NewReader("{\n  \"event_name\": \"checkout_completed\",\n  \"q\": \"{\\\"metadata.country\\\": \\\"US\\\"}\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"bucket_size_ms\": 86400000,\n  \"max_buckets\": 100,\n  \"metrics\": [\n    {\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    },\n    {\n      \"field\": \"user_id\",\n      \"function\": \"count_unique\",\n      \"name\": \"unique_users\"\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/timeseries")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event_name\": \"checkout_completed\",\n  \"q\": \"{\\\"metadata.country\\\": \\\"US\\\"}\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"bucket_size_ms\": 86400000,\n  \"max_buckets\": 100,\n  \"metrics\": [\n    {\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    },\n    {\n      \"field\": \"user_id\",\n      \"function\": \"count_unique\",\n      \"name\": \"unique_users\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"q\": \"{\\\"metadata.country\\\": \\\"US\\\"}\",\n  \"start_time\": \"2026-07-03T00:00:00Z\",\n  \"end_time\": \"2026-08-02T00:00:00Z\",\n  \"bucket_size_ms\": 86400000,\n  \"max_buckets\": 100,\n  \"metrics\": [\n    {\n      \"function\": \"count\",\n      \"name\": \"event_count\"\n    },\n    {\n      \"field\": \"user_id\",\n      \"function\": \"count_unique\",\n      \"name\": \"unique_users\"\n    }\n  ]\n}"

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

{
  "bucket_interval": 86400000,
  "bucket_count": 30,
  "event_name": "checkout_completed",
  "totals": {
    "event_count": 3840,
    "unique_users": 612
  },
  "buckets": [
    {
      "bucket": "2026-08-01",
      "metrics": {
        "event_count": 112,
        "unique_users": 47
      }
    },
    {
      "bucket": "2026-08-02",
      "metrics": {
        "event_count": 128,
        "unique_users": 54
      }
    }
  ]
}

{
  "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 time-bucketed event aggregation.

event_name

string | null

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

Example:

"checkout_completed"

string | null

Filter expression, as a JSON object serialized to a string. Same syntax as Query analytics events.

Example:

"{\"metadata.country\": \"US\"}"

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"

bucket_size_ms

integer | null

Requested bucket size in milliseconds. Base44 rounds it down to the nearest supported interval, and up to one hour when you ask for anything finer than that. Omit to pick the finest interval that fits max_buckets.

Example:

86400000

max_buckets

integer

default:1000

Maximum number of buckets to return, between 10 and 1000. Drives the interval when bucket_size_ms is omitted.

Required range: 10 <= x <= 1000

Example:

100

metrics

AggregationMetric · object[]

Between 1 and 10 metrics to compute per bucket. Defaults to an event count named event_count and a distinct-user count named unique_users.

Required array length: 1 - 10 elements

Show child attributes

Example:

[
  {
    "function": "count",
    "name": "event_count"
  },
  {
    "field": "user_id",
    "function": "count_unique",
    "name": "unique_users"
  }
]

Response

The bucketed metrics.

Response for time-bucketed event aggregation.

bucket_interval

integer

required

Interval Base44 bucketed by, in milliseconds.

Example:

86400000

bucket_count

integer

required

Number of buckets returned.

Example:

30

event_name

string | null

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

Example:

"checkout_completed"

totals

Totals · object

Each metric computed over the whole range at once, keyed by metric name. Not the sum of the buckets: count_unique counts distinct values across the range.

Show child attributes

Example:

{ "event_count": 3840, "unique_users": 612 }

buckets

TimeBucket · object[]

The buckets, oldest first. Buckets with no matching events are omitted rather than reported as zero.

Show child attributes

Example:

[
  {
    "bucket": "2026-08-01",
    "metrics": { "event_count": 112, "unique_users": 47 }
  },
  {
    "bucket": "2026-08-02",
    "metrics": { "event_count": 128, "unique_users": 54 }
  }
]

⌘I

App Management API (Beta)

Entities API (Beta)

Virality API (Beta)

Analytics API (Beta)

Monitoring API

Audit Logs API

Aggregate analytics events over time

Authorizations

Path Parameters

Body

Response