> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Register a User Analysis Query > Registers an asynchronous User Property Analysis (UPA) query and returns a `request_id`. User Property Analysis computes counts, distinct-value counts, distributions, and aggregations over user attributes for a cohort of users. Use the `request_id` with [Get Query Status](/api/analytics-queries/get-query-status) to poll for completion, then [Get Query Results](/api/analytics-queries/get-query-results) to fetch the resolved series. #### Rate Limit The rate limits are at the workspace level. A maximum of 5 requests per second, 15 requests per minute, and 100 requests per hour are allowed per workspace. ## OpenAPI ````yaml /api/analytics-query/analytics-query.yaml post /v5/analytics/user-analysis openapi: 3.0.3 info: title: MoEngage Analytics Query API version: '5.0' description: > Asynchronous REST APIs to run MoEngage Analytics queries — Behavior, Funnels, Retention, Session/Source (BFRS) and User Property Analysis (UPA) — and retrieve their results. These queries are asynchronous. A `POST` registers the query and immediately returns a `request_id`; a worker executes the query; you then poll the status and fetch the results: 1. **Submit** — `POST` one of the analysis endpoints. The response echoes the analysis `type` and returns a `request_id`. 2. **Poll** — `GET /v5/analytics/query/{request_id}/status` until `status` is `SUCCESSFUL` (or `FAILED`). 3. **Fetch** — `GET /v5/analytics/query/{request_id}/results` to retrieve the resolved series. servers: - url: https://api-{dc}.moengage.com description: MoEngage API Server variables: dc: default: '01' description: >- The 'dc' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of 'dc' in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. security: - basicAuth: [] tags: - name: Analytics Queries description: >- Register asynchronous BFRS and UPA analytics queries, then poll status and fetch results. paths: /v5/analytics/user-analysis: post: tags: - Analytics Queries summary: Register a User Analysis Query description: > Registers an asynchronous User Property Analysis (UPA) query and returns a `request_id`. User Property Analysis computes counts, distinct-value counts, distributions, and aggregations over user attributes for a cohort of users. Use the `request_id` with [Get Query Status](/api/analytics-queries/get-query-status) to poll for completion, then [Get Query Results](/api/analytics-queries/get-query-results) to fetch the resolved series. operationId: submitUserAnalysisQuery requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserAnalysisQueryRequest' examples: Total Count: summary: Total Count value: version: '2.0' type: user_analysis analysis_type: total_count user_properties: - id: A property: action_name: City executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: string extract_type: '' aggregation: {} segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments distribution: {} timerange: {} granularity: e chart_type: column count_type: number split_by: [] Unique Count: summary: Unique Count value: version: '2.0' type: user_analysis analysis_type: distinct_count user_properties: - id: A property: action_name: City executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: string extract_type: '' aggregation: {} segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments distribution: {} timerange: {} granularity: e chart_type: column count_type: number split_by: [] Distribution - Auto: summary: Distribution Auto value: version: '2.0' type: user_analysis analysis_type: distribution user_properties: - id: A property: action_name: City executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: string extract_type: '' aggregation: {} segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments distribution: type: auto from: -1 to: -1 interval: -1 timerange: {} granularity: e chart_type: column count_type: number split_by: [] Distribution - Custom: summary: Distribution Custom value: version: '2.0' type: user_analysis analysis_type: distribution user_properties: - id: A property: action_name: Order Value executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: double extract_type: '' aggregation: {} segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments distribution: type: custom from: 0 to: 10 interval: 1 timerange: {} granularity: e chart_type: column count_type: number split_by: [] Aggregation: summary: Aggregation value: version: '2.0' type: user_analysis analysis_type: aggregation user_properties: - id: A property: action_name: Order Value executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: double extract_type: '' aggregation: operation: sum percentile_value: -1 segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments distribution: {} timerange: {} granularity: e chart_type: column count_type: number split_by: [] Email Domain Analysis: summary: Email Domain Analysis value: version: '2.0' type: user_analysis analysis_type: email_domain_analysis user_properties: - id: A property: action_name: u_em executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: string extract_type: '' aggregation: {} segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments distribution: {} timerange: {} granularity: e chart_type: column count_type: number split_by: [] responses: '200': description: >- Query registered. Poll status and fetch results with `data.request_id`. content: application/json: schema: $ref: '#/components/schemas/QueryRegistration' example: response_id: 98fa8c1b-cb3f-4d29-b30e-d9e74dfb4adc type: user_analysis data: request_id: REQUEST_ID '400': $ref: '#/components/responses/ValidationFailed' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '428': $ref: '#/components/responses/QuotaExceeded' '500': $ref: '#/components/responses/InternalError' components: schemas: UserAnalysisQueryRequest: type: object description: Request body for registering a User Property Analysis (UPA) query. required: - version - type - analysis_type - user_properties - segmentation - distribution - timerange - granularity - chart_type - count_type - split_by properties: version: type: string description: Payload schema version. example: '2.0' type: type: string description: The analysis type. Must be `user_analysis` for this endpoint. enum: - user_analysis analysis_type: type: string description: > The user-property computation to run — `total_count` (all users in scope), `distinct_count` (distinct values of the attribute), `distribution` (how users are spread across the attribute's values, using automatic or custom buckets), `aggregation` (sum, minimum, maximum, average, median, or percentile), or `email_domain_analysis`. enum: - total_count - distinct_count - distribution - aggregation - email_domain_analysis example: distribution user_properties: type: array description: > The user attributes to analyze. Include 1 to 5 properties. When more than one is provided, results are cross-tabulated across them. minItems: 1 maxItems: 5 items: type: object properties: id: type: string description: >- Identifier for this property within the query (for example, `A`). example: A property: type: object description: The attribute definition and any attribute-level filters. properties: action_name: type: string description: The user attribute to analyze. example: u_l_a filter_type: type: string description: The kind of attribute being analyzed. example: user_attributes executed: type: boolean description: Whether the attribute condition must be satisfied. execution: type: object description: Execution criteria for the attribute condition. attributes: $ref: '#/components/schemas/FilterGroup' pii: type: boolean description: >- Whether the attribute is marked as personally identifiable information. encrypted: type: boolean description: Whether the attribute is stored encrypted. projection: type: object description: > How the attribute's value is formatted before results are grouped. For example, a datetime attribute projected as a date returns buckets like `19 May 2023`, and a boolean attribute returns the strings `true` and `false`. Pass an empty object to use the attribute's raw value. properties: data_type: type: string description: The attribute's underlying data type. example: datetime extract_type: type: string description: > The part of the value to project — for example, `date` to bucket a datetime attribute by calendar date. example: date object_projection: type: object description: > Projection configuration for object-type attributes, naming the nested key within the object to analyze. Pass an empty object for non-object attributes. aggregation: type: object description: > The aggregation to compute when `analysis_type` is `aggregation` — for example sum, minimum, maximum, average, median, distinct count, or a percentile from 1 to 100. Pass an empty object for other analysis types. segmentation: $ref: '#/components/schemas/Segmentation' distribution: allOf: - $ref: '#/components/schemas/BucketDistribution' description: > Distribution configuration. Custom distributions apply to numerical attributes only. Use `type: auto` for automatic bucketing. example: type: custom from: 0 to: 10 interval: 1 timerange: $ref: '#/components/schemas/Timerange' granularity: type: string description: > Time bucket for the series — `d` (day), `w` (week), `m` (month), `y` (year), or `e` (entire range). enum: - d - w - m - 'y' - e example: e chart_type: type: string description: Visual representation of the result. enum: - line - area - bar - column - euler - pie example: column count_type: type: string description: > Whether metrics are returned as absolute counts (`number`) or as percentages (`percentage`). enum: - number - percentage example: number split_by: type: array description: Attributes to break the result down by. Include up to 10. maxItems: 10 items: $ref: '#/components/schemas/UserAttributeReference' example: - attr_type: user data_type: string encrypted: false name: moe_ip_country pii: false readable_name: Last Known Country chart_sort_type: type: string description: Sort order applied to the result series. enum: - ascending - descending QueryRegistration: type: object description: >- Acknowledgement that a query was registered. Use `data.request_id` to poll status and fetch results. properties: response_id: $ref: '#/components/schemas/ResponseId' type: type: string description: The analysis type echoed back for the registered query. data: type: object properties: request_id: type: string description: >- Identifier of the registered query. Use it with the status and results endpoints. example: REQUEST_ID FilterGroup: type: object description: > A group of filter criteria combined by a logical operator. Used to define segmentation and event-level conditions. properties: included_filters: type: object description: > Criteria a user must match. For the supported filter payload and fields, see [Create Filter Segment](/api/filter-segments/create-filter-segment). properties: filter_operator: type: string description: The logical operator used to combine the filters in this group. enum: - and - or filters: type: array description: > The individual filter criteria. Each item is a filter object whose structure varies by `filter_type` (common values: `actions`, `user_attributes`, `custom_segments`). items: type: object Segmentation: type: array description: > Segments used to scope the analysis to a subset of users. Include up to 5 segments. To analyze all users, pass a single segment with the `All Users` custom segment. maxItems: 5 items: type: object properties: filters: $ref: '#/components/schemas/FilterGroup' BucketDistribution: type: object description: > Bucketing configuration for a distribution analysis. Use `auto` to let MoEngage choose the buckets, or `custom` to define your own range and interval. properties: type: type: string description: Whether buckets are chosen automatically or defined by you. enum: - auto - custom example: custom from: type: integer description: The lower bound of the first bucket. Use -1 when `type` is `auto`. example: 0 to: type: integer description: The upper bound of the last bucket. Use -1 when `type` is `auto`. example: 10 interval: type: integer description: The width of each bucket. Use -1 when `type` is `auto`. example: 1 Timerange: type: object description: The time window the analysis runs over. properties: start: type: string description: Start of the window, in `YYYY-MM-DD HH:MM:SS` (workspace time zone). example: '2026-06-09 00:00:00' end: type: string description: End of the window, in `YYYY-MM-DD HH:MM:SS` (workspace time zone). example: '2026-06-16 23:59:59' label: type: string description: Human-readable label for the window, as shown in the dashboard. example: Last 7 Days dt_label: type: string description: Relative-range keyword the label maps to. example: last value: type: integer description: >- Numeric component of a relative range (for example, 7 for the last 7 days). example: 7 UserAttributeReference: type: object description: >- A reference to a user attribute used for splitting User Analysis results. properties: attr_type: type: string description: The category the attribute belongs to. example: user name: type: string description: The stored name of the user attribute. example: moe_ip_country readable_name: type: string description: The attribute's display name, as shown in the MoEngage dashboard. example: Last Known Country data_type: type: string description: The attribute's data type. example: string encrypted: type: boolean description: Whether the attribute is stored encrypted. example: false pii: type: boolean description: >- Whether the attribute is marked as personally identifiable information. example: false ResponseId: type: string description: >- A unique identifier for the response, useful for correlating logs and support requests. example: fc803857-632e-4bf0-8df1-fbc2bdeedb66 ErrorResponse: type: object required: - error - response_id description: > Standard MoEngage error envelope, returned by the service. Authentication and authorization failures (401 and 403) are returned by the API gateway in a different format — see those responses for details. properties: error: type: object required: - code - message properties: code: type: string description: A machine-readable error code. enum: - VALIDATION_FAILED - BAD_REQUEST - NOT_FOUND - QUOTA_EXCEEDED - INTERNAL_ERROR message: type: string description: A human-readable description of the error. doc_url: type: string description: A link to documentation about this error, when available. response_id: $ref: '#/components/schemas/ResponseId' GatewayAuthError: type: object description: > Authentication or authorization failure returned by the API gateway. The body is JSON, but the gateway sends it with `Content-Type: text/plain`. properties: code: type: string description: > A machine-readable code identifying the failure, such as `ER001` when credentials are missing or invalid, or `ER007` when the credentials do not have access to the route. example: ER001 target: type: string description: The stage of the request that failed. example: Authentication Invalid message: type: string description: A human-readable description of the failure. example: Auth validation failed. responses: ValidationFailed: description: >- Validation failed — a required field is missing, a value is invalid, or a documented limit is exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: VALIDATION_FAILED message: >- analysis_type - Enum doesnt allow value: eventsdfg, allowed values: [events, users, session, aggregation, aggregation_distribution, total_events_per_user, attribute_aggregation_per_user] : 'eventsdfg' doc_url: https://www.moengage.com/docs/api/analytics-queries/ response_id: 01306019-419a-4728-ad82-9d522464f33a Unauthorized: description: > This response is returned when the credentials are missing or invalid. The API gateway generates this response before the request reaches the service, so it does not use the standard error envelope. The body is JSON, but the gateway sends it with `Content-Type: text/plain`. Parse it accordingly. content: text/plain: schema: $ref: '#/components/schemas/GatewayAuthError' example: code: ER001 target: Authentication Invalid message: Auth validation failed. Forbidden: description: > This response is returned when the credentials are valid but do not have access to this route or workspace. The API gateway generates this response before the request reaches the service, so it does not use the standard error envelope. The body is JSON, but the gateway sends it with `Content-Type: text/plain`. Parse it accordingly. content: text/plain: schema: $ref: '#/components/schemas/GatewayAuthError' example: code: ER007 target: Authentication Invalid message: Auth validation failed. QuotaExceeded: description: >- This response is returned when the workspace has reached its monthly Fair Usage Policy (FUP) limit for analytics usage. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: QUOTA_EXCEEDED message: >- Your workspace has reached its monthly Fair Usage Policy limit for analytics usage. Please contact your Customer Success Manager to expand your quota. doc_url: https://www.moengage.com/docs/api/analytics-queries/ response_id: 714b4690eba1deb53b065d92277e2910 InternalError: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL_ERROR message: An unexpected error occurred while processing the request. doc_url: https://www.moengage.com/docs/api/analytics-queries/ response_id: dcc4fd00-2980-41a5-94b3-ad4844ae3d72 securitySchemes: basicAuth: type: http scheme: basic description: > Authentication is done via Basic Auth. This requires a Base64-encoded string of your credentials in the format `username:password`. - **Username**: Use your MoEngage Workspace ID (also known as the App ID). Find it in the MoEngage dashboard at **Settings** > **Account** > **API keys**. - **Password**: Use an API key from **Settings** > **Account** > **API keys**. Refer to [API Key Dashboard](/user-guide/settings/account/api-and-api-keys/api-key-dashboard) for details on creating and managing API keys. ````