---
title: "queryEvents"
method: POST
path: "/v1/app-configurations/{appId}/events"
tags: ["App Analytics"]
---

# queryEvents

`POST /v1/app-configurations/{appId}/events`

Query analytics events for a specific app with flexible filtering

## Path parameters

- `appId` string, required

## Request body

- EventsQuery
  - `time_range` object — Either use preset OR start+end
    - `start` string, date-time — Start time (ISO 8601)
    - `end` string, date-time — End time (ISO 8601)
    - `preset` '1h' | '6h' | '24h' | '7d' | '30d' — Predefined time range (alternative to start/end)
  - `filters` object
    - `source` ComponentType[] — Filter by component types
    - `component_id` string[] — Filter by specific component IDs
    - `event_type` string[] — Filter by event types
    - `correlation_id` string — Filter by correlation ID for tracing
  - `aggregation` object
    - `group_by` string[] — Group results by specified fields
    - `metrics` string[] — Metrics to calculate
  - `pagination` object
    - `page` integer
    - `page_size` integer
  - `sort` object
    - `field` 'timestamp' | 'event_type' | 'component_id'
    - `order` 'asc' | 'desc'

## Response `200`

Analytics events

- EventsQueryResponse
  - `query` EventsQuery
    - `time_range` object — Either use preset OR start+end
      - `start` string, date-time — Start time (ISO 8601)
      - `end` string, date-time — End time (ISO 8601)
      - `preset` '1h' | '6h' | '24h' | '7d' | '30d' — Predefined time range (alternative to start/end)
    - `filters` object
      - `source` ComponentType[] — Filter by component types
      - `component_id` string[] — Filter by specific component IDs
      - `event_type` string[] — Filter by event types
      - `correlation_id` string — Filter by correlation ID for tracing
    - `aggregation` object
      - `group_by` string[] — Group results by specified fields
      - `metrics` string[] — Metrics to calculate
    - `pagination` object
      - `page` integer
      - `page_size` integer
    - `sort` object
      - `field` 'timestamp' | 'event_type' | 'component_id'
      - `order` 'asc' | 'desc'
  - `results` union
    - RawEvents
      - `type` 'raw'
      - `events` AppEventData[]
        - `app_id` string, required — ID of the app configuration
        - `version` string, required — Version of the app configuration
        - `event_id` string
        - `component_id` string, required
        - `timestamp` string
        - `correlation_id` string
        - `event_type` 'ERROR' | 'WARNING' | 'INFO', required
        - `source` 'CUSTOM_JOURNEY_BLOCK' | 'PORTAL_EXTENSION' | 'CUSTOM_FLOW_ACTION' | 'ERP_INFORM_TOOLKIT', required — Type of app component
        - `actor` Actor, required
          - `org_id` string — Organization ID of the actor
          - `user_id` string — User ID of the actor
          - `type` 'user' | 'system', required — Type of the actor (e.g., user, system)
        - `details` object — Details about the event
    - AggregatedEvents
      - `type` 'aggregated'
      - `groups` object[]
        - `dimensions` object — The grouped dimensions e.g., "source": "CUSTOM_JOURNEY_BLOCK", "event_type": "ERROR"
        - `metrics` object
          - `count` integer
          - `error_rate` number
  - `pagination` object
    - `page` integer
    - `page_size` integer
    - `total_items` integer
    - `has_next` boolean

## Other responses

- `400` — Invalid query parameters
- `404` — App configuration not found

---

[API](https://skmtc.net/epilot/apis/app-api.md) · [All operations](https://skmtc.net/epilot/apis/app-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/app-api/revisions/03b93188c6d4/schema)