> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/analytics/timeseries
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/analytics/timeseries:
post:
summary: Aggregate analytics events over time
description: >-
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.
operationId: timeseries_api_apps__app_id__analytics_timeseries_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose analytics to read.
title: App Id
description: ID of the app whose analytics to read.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimeseriesRequest'
responses:
'200':
description: The bucketed metrics.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeseriesResponse'
'401':
description: Missing or invalid credentials.
'403':
description: You don't have access to this app.
'404':
description: App not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TimeseriesRequest:
properties:
event_name:
anyOf:
- type: string
- type: 'null'
title: Event Name
description: >-
Name of the event to aggregate. Omit to aggregate every event the
app tracks.
example: checkout_completed
q:
anyOf:
- type: string
- type: 'null'
title: Q
description: >-
Filter expression, as a JSON object serialized to a string. Same
syntax as [Query analytics
events](/api-reference/query-analytics-events).
example: '{"metadata.country": "US"}'
start_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Start Time
description: Start of the time range. Defaults to 30 days ago.
example: '2026-07-03T00:00:00Z'
end_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: End Time
description: End of the time range. Defaults to now.
example: '2026-08-02T00:00:00Z'
bucket_size_ms:
anyOf:
- type: integer
- type: 'null'
title: Bucket Size Ms
description: >-
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:
type: integer
maximum: 1000
minimum: 10
title: Max Buckets
description: >-
Maximum number of buckets to return, between 10 and 1000. Drives the
interval when `bucket_size_ms` is omitted.
default: 1000
example: 100
metrics:
items:
$ref: '#/components/schemas/AggregationMetric'
type: array
maxItems: 10
minItems: 1
title: Metrics
description: >-
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`.
example:
- function: count
name: event_count
- field: user_id
function: count_unique
name: unique_users
type: object
title: TimeseriesRequest
description: Request for time-bucketed event aggregation.
TimeseriesResponse:
properties:
event_name:
anyOf:
- type: string
- type: 'null'
title: Event Name
description: >-
The event name that was aggregated, or `null` when the request
covered every event.
example: checkout_completed
bucket_interval:
type: integer
title: Bucket Interval
description: Interval Base44 bucketed by, in milliseconds.
example: 86400000
bucket_count:
type: integer
title: Bucket Count
description: Number of buckets returned.
example: 30
totals:
additionalProperties:
anyOf:
- type: number
- type: integer
type: object
title: Totals
description: >-
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:
event_count: 3840
unique_users: 612
buckets:
items:
$ref: '#/components/schemas/TimeBucket'
type: array
title: Buckets
description: >-
The buckets, oldest first. Buckets with no matching events are
omitted rather than reported as zero.
example:
- bucket: '2026-08-01'
metrics:
event_count: 112
unique_users: 47
- bucket: '2026-08-02'
metrics:
event_count: 128
unique_users: 54
type: object
required:
- bucket_interval
- bucket_count
title: TimeseriesResponse
description: Response for time-bucketed event aggregation.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AggregationMetric:
properties:
name:
type: string
maxLength: 64
pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
title: Name
description: >-
Name to report this metric under. It becomes a key in `metrics` and
`totals` in the response.
example: unique_users
function:
type: string
enum:
- count
- count_unique
- sum
- avg
- min
- max
- p50
- p90
- p95
- p99
title: Function
description: >-
How to aggregate the field. `count` counts events, `count_unique`
counts distinct values, and the rest compute over the field's
numeric values.
example: count_unique
field:
anyOf:
- type: string
maxLength: 128
pattern: >-
^(properties\.)?[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$
- type: 'null'
title: Field
description: >-
Field to aggregate. Required for every function except `count`.
Top-level fields are `user_id`, `session_id`, `event_id`,
`event_name`, and `page_url`. Prefix a key with `metadata.` for the
device information Base44 captures itself: `metadata.device_type`,
`metadata.os`, and `metadata.country`. Any other name reads as an
event property, so `amount` and `properties.amount` mean the same
thing.
example: user_id
type: object
required:
- name
- function
title: AggregationMetric
description: A single aggregation metric to compute.
TimeBucket:
properties:
bucket:
type: string
title: Bucket
description: >-
Start of the bucket. A date-time for intervals under a day, and a
date for intervals of a day or longer.
example: '2026-08-02'
metrics:
additionalProperties:
anyOf:
- type: number
- type: integer
type: object
title: Metrics
description: >-
The requested metrics for this bucket, keyed by the `name` you gave
each one.
example:
event_count: 128
unique_users: 54
type: object
required:
- bucket
title: TimeBucket
description: A single time bucket with computed metrics.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````