Sign in

Query analytics events

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

Returns the app's individual analytics events for one event name, newest first, with the properties the app sent on each one.

The time range defaults to the last 7 days. To use a different range, put timestamp bounds in the q filter, for example {"timestamp": {"gte": "2026-08-01T00:00:00Z", "lt": "2026-08-08T00:00:00Z"}}. Base44 applies the bounds as timestamp >= start and timestamp < end, so gt behaves like gte and lte behaves like lt. Events are kept for 60 days, so an older range returns nothing.

Page through the results with limit and offset. When has_more is true, send the returned next_offset as the next request's offset. total counts every matching event, not just the ones on this page.

q is a JSON object serialized to a string. Each key is a field, and its value is either a literal to match for equality or an object of operators, as in {"user_id": "6891ab34d2f07e5c1b9a2d48", "properties.amount": {"gte": 50}}. The comparison operators are eq, ne, gt, gte, lt, lte, in, nin, and regex. Combine expressions with and or or, each taking an array, and negate one with not.

event_id, event_name, timestamp, user_id, session_id, and page_url are top-level fields. Every other key reads as an event property, so plan and properties.plan mean the same thing. Get the available property keys from List analytics event properties. Prefix a key with metadata. to filter on the device information Base44 captures itself: metadata.device_type, metadata.os, and metadata.country.

<Warning>regex 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. Add "options": "i" next to it for a case-insensitive match.</Warning>

<Warning>The response includes fields beyond the ones documented here. Don't use any undocumented fields, as they can change at any time.</Warning>

post/api/apps/{app_id}/analytics/query

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 required

Name of the event to query, exactly as the app tracked it.

qstring nullable

Filter expression, as a JSON object serialized to a string. Omit to return every event with this name in the time range.

offsetinteger

Number of events to skip before the page starts. Pass the next_offset from the previous response to get the next page.

limitinteger

Maximum number of events to return, between 1 and 1000.

Example request

{
  "event_name": "checkout_completed",
  "q": "{\"properties.plan\": {\"in\": [\"pro\", \"elite\"]}}",
  "limit": 100
}

Response

The matching events.

totalinteger required

Number of events matching the query, across all pages.

has_moreboolean required

Whether more events match beyond this page.

next_offsetinteger nullable

Offset to pass as offset to get the next page, or null when has_more is false.

Example response

{
  "total": 1842,
  "events": [
    {
      "event_id": "4f1c9a02-8b7d-4e6a-9c31-5d2e7f8a0b41",
      "event_name": "checkout_completed",
      "metadata": {
        "country": "US",
        "device_type": "mobile",
        "os": "iOS"
      },
      "page_url": "https://my-crm.base44.app/checkout",
      "properties": {
        "plan": "pro",
        "amount": 49.9
      },
      "session_id": "9a7c2f10-3b4d-4e58-8c61-0d2f5a7b9e13",
      "timestamp": "2026-08-02T14:30:00",
      "user_id": "6891ab34d2f07e5c1b9a2d48"
    }
  ],
  "has_more": true,
  "next_offset": 100
}

Changes