> ## 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 use any undocumented fields, as they can change at any time.</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 use any undocumented fields, as they can change at any
        time.</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: The matching events.
          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
    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.
          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. `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.

````