Sign in

Aggregate analytics events over time

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

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

Path parameters

app_idstring required

ID of the app whose analytics to read.

ID of the app whose analytics to read.

Request body

event_namestring nullable

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

qstring nullable

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

start_timestring date-time nullable

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

end_timestring date-time nullable

End of the time range. Defaults to now.

bucket_size_msinteger nullable

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.

max_bucketsinteger

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

Example request

{
  "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"
    }
  ]
}

Response

The bucketed metrics.

event_namestring nullable

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

bucket_intervalinteger required

Interval Base44 bucketed by, in milliseconds.

bucket_countinteger required

Number of buckets returned.

totalsobject

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.

Example response

{
  "event_name": "checkout_completed",
  "bucket_interval": 86400000,
  "bucket_count": 30,
  "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
      }
    }
  ]
}

Changes