> ## 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 Funnels Query > Registers an asynchronous Funnels analysis query and returns a `request_id`. Funnels analysis measures step-by-step conversion and drop-off across an ordered sequence of events. 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/funnels 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/funnels: post: tags: - Analytics Queries summary: Register a Funnels Query description: > Registers an asynchronous Funnels analysis query and returns a `request_id`. Funnels analysis measures step-by-step conversion and drop-off across an ordered sequence of events. 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: submitFunnelsQuery requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FunnelsQueryRequest' example: events: - from_step: null to_step: null step_type: include step_number: 1 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: [] - from_step: null to_step: null step_type: include step_number: 2 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 funnel_type: user_funnel timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 7 Days dt_label: last value: 7 grouped_by_meta: {} grouped_by: [] holding_attributes_meta: {} holding_attributes: [] funnel_window: 86400 funnel_window_multiplier: 86400 strict_order: false distribution: {} countType: number showConversionEventOnly: false chart_type: column comparison_timerange: {} version: '2.0' type: funnel granularity: e chart_plot_type: linear 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: 498b1a8f-027b-4aba-b71e-2f6fac76deba type: funnels data: request_id: 6a5621f99f22da29f1ec05ed '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: FunnelsQueryRequest: type: object description: Request body for registering a Funnels analysis query. required: - type - events - funnel_type - timerange properties: version: type: string description: Payload schema version. example: '2.0' type: type: string description: The analysis type. Must be `funnel` for this endpoint. enum: - funnel events: type: array description: > The ordered steps of the funnel. Include 2 to 10 steps. Each step defines the event and attribute conditions a user must satisfy to be counted at that step. minItems: 2 maxItems: 10 items: type: object properties: step_number: type: integer description: The 1-based position of this step in the funnel. example: 1 step_type: type: string description: >- Whether users who match this step are included in or excluded from the funnel. enum: - include - exclude from_step: type: integer nullable: true description: >- For a distribution funnel, the step the window is measured from. Null otherwise. to_step: type: integer nullable: true description: >- For a distribution funnel, the step the window is measured to. Null otherwise. c_at_trigger_seg_v2: $ref: '#/components/schemas/FilterGroup' c_at_act_seg_v2: $ref: '#/components/schemas/FilterGroup' segmentation: $ref: '#/components/schemas/Segmentation' funnel_type: type: string description: > The kind of funnel to compute — `user_funnel` (standard conversion), `event_time_to_convert` (time-to-convert distribution between two steps), or `user_frequency` (frequency distribution of repeated actions between two steps). enum: - user_funnel - event_time_to_convert - user_frequency grouped_by: type: array description: Attributes to split the funnel by. Include up to 3. maxItems: 3 items: type: object grouped_by_meta: type: object description: Metadata for the `grouped_by` attributes. holding_attributes: type: array description: Attributes held constant across funnel steps. Include up to 3. maxItems: 3 items: type: object holding_attributes_meta: type: object description: Metadata for the `holding_attributes`. funnel_window: type: integer description: >- The conversion window in seconds within which users must complete the funnel. example: 86400 funnel_window_multiplier: type: integer description: Multiplier applied to the funnel window. example: 86400 strict_order: type: boolean description: Whether steps must be performed in the exact order defined. example: false distribution: type: object description: > Distribution configuration for `event_time_to_convert` and `user_frequency` funnels. When using custom buckets, include at most 25 buckets. Pass an empty object for a standard funnel. countType: type: string description: >- Whether metrics are returned as absolute counts or percentages, such as `number`. example: number showConversionEventOnly: type: boolean description: Whether to return only the conversion event's metrics. example: false chart_type: type: string description: >- Visual representation of the result, such as `line`, `bar`, or `column`. example: column comparison_timerange: type: object description: > A second time range to compare against. Time comparison is supported only on line, bar, and column charts, and cannot be combined with custom-segment comparison (2 or more segments). Pass an empty object for no comparison. 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). When hourly, the time range must not exceed 31 days. enum: - h - d - w - m - e example: e chart_plot_type: type: string description: Plot scale for the chart, such as `linear`. example: linear 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). ````