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

# 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](/api-reference/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 rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/analytics/query
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/query:
    post:
      summary: Query analytics events
      description: >-
        <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](/api-reference/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 rely on undocumented response fields, as they can change at any
        time. Send only the fields documented here. Other request fields are not
        supported and their behavior can change.</Warning>
      operationId: query_events_api_apps__app_id__analytics_query_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/QueryEventsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsEventPage'
        '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:
    QueryEventsRequest:
      properties:
        event_name:
          type: string
          title: Event Name
          description: Name of the event to query, exactly as the app tracked it.
          example: checkout_completed
        q:
          anyOf:
            - type: string
            - type: 'null'
          title: Q
          description: >-
            Filter expression, as a JSON object serialized to a string. Omit to
            return every event with this name in the time range.
          example: '{"properties.plan": {"in": ["pro", "elite"]}}'
        offset:
          type: integer
          minimum: 0
          title: Offset
          description: >-
            Number of events to skip before the page starts. Pass the
            `next_offset` from the previous response to get the next page.
          default: 0
          example: 0
        limit:
          type: integer
          maximum: 1000
          minimum: 1
          title: Limit
          description: Maximum number of events to return, between 1 and 1000.
          default: 100
          example: 100
      type: object
      required:
        - event_name
      title: QueryEventsRequest
      description: Query request for analytics events with filter expression support.
    AnalyticsEventPage:
      properties:
        total:
          type: integer
          title: Total
          description: Number of events matching the query, across all pages.
          example: 1842
        events:
          items:
            $ref: '#/components/schemas/AnalyticsEvent'
          type: array
          title: Events
          description: The requested page of events, newest first.
          example:
            - 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:
          type: boolean
          title: Has More
          description: Whether more events match beyond this page.
          example: true
        next_offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Next Offset
          description: >-
            Offset to pass as `offset` to get the next page, or `null` when
            `has_more` is `false`.
          example: 100
      type: object
      required:
        - total
        - events
        - has_more
      title: AnalyticsEventPage
      description: One page of analytics events matching a query.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AnalyticsEvent:
      properties:
        event_id:
          type: string
          title: Event Id
          description: ID of the event.
          example: 4f1c9a02-8b7d-4e6a-9c31-5d2e7f8a0b41
        event_name:
          type: string
          title: Event Name
          description: Name of the event.
          example: checkout_completed
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: >-
            Time the event occurred, as reported by the app, as a UTC timestamp
            in ISO 8601 format.
          example: '2026-08-02T14:30:00'
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: >-
            ID of the app user who triggered the event, or `null` if it was not
            attributed to one.
          example: 6891ab34d2f07e5c1b9a2d48
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: Session the event belongs to, or `null` if the app sent none.
          example: 9a7c2f10-3b4d-4e58-8c61-0d2f5a7b9e13
        page_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Url
          description: >-
            URL of the page the event happened on, or `null` if the app sent
            none.
          example: https://my-crm.base44.app/checkout
        properties:
          additionalProperties: true
          type: object
          title: Properties
          description: >-
            The custom properties the app sent with this event, or `{}` if it
            sent none. Keys and value types are whatever the app tracks.
          example:
            amount: 49.9
            plan: pro
        metadata:
          $ref: '#/components/schemas/AnalyticsEventMetadata'
          description: Device information Base44 captured when it received the event.
      type: object
      required:
        - event_id
        - event_name
        - timestamp
        - properties
        - metadata
      title: AnalyticsEvent
    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
    AnalyticsEventMetadata:
      properties:
        device_type:
          anyOf:
            - type: string
              enum:
                - desktop
                - mobile
                - tablet
            - type: 'null'
          title: Device Type
          description: >-
            Device the event came from, derived from the request's user agent,
            or `null` when the app sent no user agent.
          example: mobile
        os:
          anyOf:
            - type: string
            - type: 'null'
          title: Os
          description: >-
            Operating system the event came from, or `null` when it could not be
            derived.
          example: iOS
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: >-
            Two-letter country code the event came from. The value is `null`
            when the request reached Base44 without a country header, `XX` when
            the country is unknown, and `T1` for traffic over Tor.
          example: US
      type: object
      title: AnalyticsEventMetadata
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````