> ## 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.

# Analytics API Overview

> Get started with the Base44 Analytics API

<Note>
  The Analytics API is in beta. Its endpoints and responses may change.
</Note>

Your app records an analytics event every time it calls `base44.analytics.track()`, with whatever custom properties you pass. The Analytics API reads those events back: the raw rows, aggregates over time, breakdowns by any field, and the counts behind an active-users dashboard.

Use the Analytics API to:

* Discover what an app tracks, and which properties each event carries.
* Read individual events, filtered and paged.
* Chart events over time, with the metrics you choose per bucket.
* Rank events by a field, such as the busiest pages or the countries your users come from.
* Read how many users are active, live, and inactive.

## Prerequisites

* A personal API key. See [Authentication](/developers/references/app-management/get-started/authentication) to get one. These endpoints share the App Management API's `api_key` header and base URL.
* An app you can edit.

## App ID

Every endpoint includes the app's ID in the URL path as `app_id`.

**To get your app ID:**

1. Go to [app.base44.com](https://app.base44.com/).
2. Open your app in the app editor.
3. Copy the app ID from the editor URL: `"https://app.base44.com/apps/<app_id>/editor"`.

## Events are kept for 60 days

Base44 deletes an analytics event 60 days after it happened, so every endpoint here answers from the last 60 days and nothing older. An event name the app stopped sending before that stops appearing entirely, and a time range that starts more than 60 days ago comes back empty rather than partial.

Plan for this if you report on longer periods: read the aggregates you need on a schedule and keep them yourself.

## Events appear a few seconds after they happen

Writes are asynchronous, so an event the app tracked seconds ago can be missing from a read. Treat a just-tracked event as eventually visible rather than immediately queryable, and do not use these endpoints to confirm that a single `track()` call landed.

## Start by discovering what the app tracks

Event names and property keys are whatever the app chose, so there is no fixed catalog to read from.

**To find what you can query:**

1. Call [List analytics event names](/api-reference/list-analytics-event-names) for the event names the app has recorded, most frequent first.
2. Call [List analytics event properties](/api-reference/list-analytics-event-properties) with one of those names for the property keys it carries.
3. Pass the name as `event_name`, and a property as `properties.<key>`, to the query and aggregation endpoints.

## Filter expressions

[Query analytics events](/api-reference/query-analytics-events) and [Aggregate analytics events over time](/api-reference/aggregate-analytics-events-over-time) take a `q` filter: a JSON object, serialized to a string, where each key is a field and each value is either a literal or an object of operators. That endpoint's reference page carries the full operator list and the field naming rules.

Two things surprise people:

<Warning>
  The `regex` operator matches a substring, not a regular expression. `{"page_url": {"regex": "/checkout"}}` matches any URL containing `/checkout`, and regular expression syntax such as `^` or `.*` matches literally.
</Warning>

`timestamp` bounds inside `q` set the time range and override `start_time` and `end_time`. Base44 applies them as `timestamp >= start` and `timestamp < end`, so `gt` behaves like `gte` and `lte` behaves like `lt`.

## Fields you can filter and group by

Three kinds of field are addressable, and the prefix decides which:

* `event_id`, `event_name`, `timestamp`, `user_id`, `session_id`, and `page_url` are top-level fields, named as they are.
* A `metadata.` prefix reads the device information Base44 captures itself: `metadata.device_type`, `metadata.os`, and `metadata.country`.
* Anything else is one of the app's own properties, so `plan` and `properties.plan` mean the same thing.

<Note>
  A property key is addressable only when it is made up of letters, digits, and underscores, and starts with a letter or an underscore. An app can track a key holding a space, a hyphen, or a leading digit, and the properties endpoint returns it, but you cannot filter or aggregate on it. Rename the property in the app to query it.
</Note>

## What counts as a user

Only events the app attributed to a user count toward the user numbers. Events tracked without a `user_id` are recorded and queryable, but they do not appear in [Get analytics user stats](/api-reference/get-analytics-user-stats).

That endpoint sorts each user into one bucket by their most recent event: active in the last 7 days, inactive for 7 to 30 days, or inactive for longer. `live_users` is counted separately, from the app's heartbeats over the last 2 minutes rather than from its events.