> ## Documentation Index > Fetch the complete documentation index at: https://moengage-analytics-query-api-docs.mintlify.site/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. ## 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' example: version: '2.0' type: user_analysis analysis_type: distribution user_properties: - id: A property: action_name: u_l_a executed: true filter_type: user_attributes execution: count: 1 type: atleast attributes: filter_operator: and filters: [] pii: false encrypted: false projection: data_type: datetime extract_type: date object_projection: {} 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: [] chart_sort_type: descending 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: 6a56220f9f22da29f1ec05f0 '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: - type - analysis_type - user_properties - segmentation 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, such as `distribution` (value distribution), a count, or an aggregation. 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 property value is projected for grouping (for example, a datetime attribute projected as a date). object_projection: type: object description: Projection configuration for object-type attributes. aggregation: type: object description: Aggregation configuration for this property. segmentation: $ref: '#/components/schemas/Segmentation' distribution: type: object description: > Distribution configuration. Custom distributions apply to numerical attributes only. Use `type: auto` for automatic bucketing. timerange: $ref: '#/components/schemas/Timerange' granularity: type: string description: > Time bucket for the series — `h` (hour), `d` (day), `w` (week), `m` (month), or `e` (entire range). enum: - h - d - w - m - e example: e chart_type: type: string description: Visual representation of the result, such as `column`. example: column count_type: type: string description: >- Whether metrics are returned as absolute counts or percentages, such as `number`. example: number split_by: type: array description: Attributes to break the result down by. Include up to 10. maxItems: 10 items: type: object 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: 6a57577219749c10af96ed2a 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' 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 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. properties: error: type: object required: - code - message properties: code: type: string description: A machine-readable error code. enum: - VALIDATION_FAILED - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - 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' 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: /api/analytics-query/analytics-query-overview response_id: 01306019-419a-4728-ad82-9d522464f33a Unauthorized: description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHORIZED message: Authentication required. doc_url: /api/analytics-query/analytics-query-overview response_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d Forbidden: description: >- The caller does not have access to this workspace or resource, or the analytics feature is not enabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: FORBIDDEN message: You do not have access to perform this action. doc_url: /api/analytics-query/analytics-query-overview response_id: c9d0e1f2-a3b4-4c5d-9e6f-7a8b9c0d1e2f 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: /api/analytics-query/analytics-query-overview 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: /api/analytics-query/analytics-query-overview 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). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**. - **Password**: Use your Data API Key, which you can find in the MoEngage dashboard at **Settings** > **Account** > **APIs**. For more information, see [Authentication](/api/introduction#authentication). ````