> ## 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 Retention Query > Registers an asynchronous Retention analysis query and returns a `request_id`. Retention analysis groups users who performed a first event into cohorts, then measures how many return to perform a second event in each later period. 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/retention 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/retention: post: tags: - Analytics Queries summary: Register a Retention Query description: > Registers an asynchronous Retention analysis query and returns a `request_id`. Retention analysis groups users who performed a first event into cohorts, then measures how many return to perform a second event in each later period. 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: submitRetentionQuery requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RetentionQueryRequest' example: version: '2.0' type: retention events: - id: first actions: - c_at_trigger_seg_v2: included_filters: filter_operator: and filters: - filter_type: actions action_name: MOE_APP_OPENED execution: type: atleast count: 1 executed: true attributes: filter_operator: and filters: [] c_at_act_seg_v2: included_filters: filter_operator: and filters: [] - id: return actions: - c_at_trigger_seg_v2: included_filters: filter_operator: and filters: - filter_type: actions action_name: UPDATE execution: type: atleast count: 1 executed: true attributes: filter_operator: and filters: [] c_at_act_seg_v2: included_filters: filter_operator: and filters: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 7 Days dt_label: last value: 7 granularity: d chart_type: line retention_type: every split_by: [] comparison_timerange: {} 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: 79b86153-abfc-4499-9d24-c955636d74a2 type: retention data: request_id: 6a5622049f22da29f1ec05ee '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: RetentionQueryRequest: type: object description: Request body for registering a Retention analysis query. required: - type - events - timerange - retention_type properties: version: type: string description: Payload schema version. example: '2.0' type: type: string description: The analysis type. Must be `retention` for this endpoint. enum: - retention events: type: array description: > Exactly two events: the `first` event that places a user into a cohort, and the `return` event measured in later periods. minItems: 2 maxItems: 2 items: type: object properties: id: type: string description: The event's role in the analysis. enum: - first - return actions: type: array description: The event and attribute conditions that define this event. items: type: object properties: c_at_trigger_seg_v2: $ref: '#/components/schemas/FilterGroup' c_at_act_seg_v2: $ref: '#/components/schemas/FilterGroup' segmentation: allOf: - $ref: '#/components/schemas/Segmentation' description: > Segments to scope the analysis (up to 5). Segmentation and `comparison_timerange` are mutually exclusive — do not send 2 or more segments together with a time comparison. timerange: $ref: '#/components/schemas/Timerange' granularity: type: string description: > Cohort period — `h` (hourly, window up to 24 hours), `d` (daily, up to 90 days), or `w` (weekly, up to 180 days). enum: - h - d - w example: d chart_type: type: string description: Visual representation of the result, such as `line`. example: line retention_type: type: string description: > How return events are counted — `every` (return in every period), `first` (first return only), or `last` (last return only). enum: - every - first - last split_by: type: array description: Attributes to break the cohorts down by. Include up to 10. maxItems: 10 items: type: object comparison_timerange: type: object description: > A second time range to compare against. Mutually exclusive with sending 2 or more segments. Pass an empty object for no comparison. 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). ````