> ## 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 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. #### Rate Limit The rate limits are at the workspace level. A maximum of 5 requests per second, 20 requests per minute, and 250 requests per hour are allowed per workspace. ## 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' examples: Funnel - Unique Users: summary: Funnel - Unique Users value: 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: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: Product Viewed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: bar comparison_timerange: {} version: '2.0' type: funnel granularity: e Funnel - All Occurrences: summary: Funnel - All Occurrences value: 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: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: Product Viewed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: event_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: bar comparison_timerange: {} version: '2.0' type: funnel granularity: e Time to Convert - Unique Users: summary: Time to convert - Unique Users value: 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: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: Product Viewed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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_time_to_convert 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: method: auto from_step: 1 to_step: 2 parameters: range: start: null end: null multiplier: null bucket: size: null multiplier: null countType: number showConversionEventOnly: false chart_type: line comparison_timerange: {} version: '2.0' type: funnel granularity: e Time to Convert - All Occurrences: summary: Time to convert - All Occurrences value: 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: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: Product Viewed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: event_time_to_convert 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: method: auto from_step: 1 to_step: 2 parameters: range: start: null end: null multiplier: null bucket: size: null multiplier: null countType: number showConversionEventOnly: false chart_type: line comparison_timerange: {} version: '2.0' type: funnel granularity: e Frequency - Unique Users: summary: Frequency - Unique Users value: 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: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: Product Viewed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and c_at_act_seg_v2: included_filters: filter_operator: and filters: [] - from_step: null to_step: null step_type: include step_number: 3 c_at_trigger_seg_v2: included_filters: filter_operator: and filters: - filter_type: actions action_name: Purchase Completed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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_frequency 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: true distribution: from_step: 1 to_step: 2 method: custom parameters: range: start: 0 end: 30 multiplier: null bucket: size: 2 multiplier: null countType: number showConversionEventOnly: false chart_type: bar comparison_timerange: {} version: '2.0' type: funnel granularity: e Frequency - All Occurrences: summary: Frequency - All Occurrences value: 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: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: Product Viewed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and c_at_act_seg_v2: included_filters: filter_operator: and filters: [] - from_step: null to_step: null step_type: include step_number: 3 c_at_trigger_seg_v2: included_filters: filter_operator: and filters: - filter_type: actions action_name: Purchase Completed execution: count: 1 type: atleast executed: true attributes: filters: [] filter_operator: and 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: event_frequency 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: true distribution: from_step: 1 to_step: 2 method: custom parameters: range: start: 0 end: 30 multiplier: null bucket: size: 2 multiplier: null countType: number showConversionEventOnly: false chart_type: bar comparison_timerange: {} version: '2.0' type: funnel granularity: e 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: funnel 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: FunnelsQueryRequest: type: object description: Request body for registering a Funnels analysis query. required: - version - type - events - segmentation - funnel_type - grouped_by - grouped_by_meta - holding_attributes - holding_attributes_meta - funnel_window - funnel_window_multiplier - distribution - chart_type - comparison_timerange - timerange - granularity 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. The `user_` values count unique users and the `event_` values count all occurrences — `user_funnel` and `event_funnel` (standard conversion), `user_time_to_convert` and `event_time_to_convert` (time-to-convert distribution between two steps), and `user_frequency` and `event_frequency` (frequency distribution of repeated actions between two steps). enum: - user_funnel - event_funnel - user_time_to_convert - event_time_to_convert - user_frequency - event_frequency grouped_by: type: array description: > Event attributes to split the funnel by. Include up to 3. Each item names the attribute to split on. maxItems: 3 items: $ref: '#/components/schemas/AttributeReference' example: - column_name: moe_device_os_version type: _s attr_type: event data_types: - string readable_name: OS Version encrypted: false pii: false grouped_by_meta: allOf: - $ref: '#/components/schemas/FunnelAttributeMeta' description: > Describes how each `grouped_by` attribute is applied across the funnel — for example, to all steps, to the first N steps, or to a specific step. Keys correspond to the attributes in `grouped_by`. Pass an empty object when `grouped_by` is empty. example: type: all_steps applied_on: -1 holding_attributes: type: array description: > Event attributes that must hold the same value across funnel steps, so only users who kept that value are counted as converted. Include up to 3. maxItems: 3 items: $ref: '#/components/schemas/AttributeReference' example: - column_name: moe_device_os_version type: _s attr_type: event data_types: - string readable_name: OS Version encrypted: false pii: false holding_attributes_meta: allOf: - $ref: '#/components/schemas/FunnelAttributeMeta' description: > Describes how each holding attribute is applied across the funnel steps. Keys correspond to the attributes in `holding_attributes`. Pass an empty object when `holding_attributes` is empty. example: type: all_steps applied_on: -1 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: allOf: - $ref: '#/components/schemas/FunnelDistribution' 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. example: method: custom from_step: 1 to_step: 2 parameters: range: start: 0 end: 10 multiplier: MINUTE bucket: size: 1 multiplier: MINUTE countType: type: string description: > Whether metrics are returned as absolute counts (`number`) or as percentages (`percentage`). enum: - number - percentage 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. enum: - line - area - bar - column - euler - pie example: column comparison_timerange: allOf: - $ref: '#/components/schemas/Timerange' 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. example: start: '2026-08-13 00:00:00' end: '2026-08-20 23:59:59' label: Previous week dt_label: prev_w value: 7 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 applied to the chart. enum: - linear - logarithmic - cumulative - rolling_sum - rolling_avg - rolling_window 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: 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' AttributeReference: type: object description: > A reference to an event, user, or device attribute used for grouping, splitting, or aggregating results. properties: attr_type: type: string description: >- The category the attribute belongs to, such as `event`, `user`, `device`, or `source`. example: event column_name: type: string description: The stored name of the attribute. example: Brand readable_name: type: string description: The attribute's display name, as shown in the MoEngage dashboard. example: Brand type: type: string description: > The internal type code for the attribute's data type, such as `_s` for string or `_f` for a numeric value. example: _s data_types: type: array description: The data types accepted for this attribute. items: type: string 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 FunnelAttributeMeta: type: object description: | Describes which funnel steps an attribute is applied to. properties: type: type: string description: > The steps the attribute applies to, such as `all_steps`, the first N steps, or a specific step. example: all_steps applied_on: type: integer description: > The step number the attribute applies to. Use -1 when the attribute applies to all steps. example: -1 FunnelDistribution: type: object description: > Distribution configuration for a time-to-convert or frequency funnel, defining the step range measured and how results are bucketed. properties: method: type: string description: Whether buckets are chosen automatically or defined by you. enum: - auto - custom example: custom from_step: type: integer description: The step the measurement starts from. example: 1 to_step: type: integer description: The step the measurement ends at. example: 2 parameters: type: object description: The range measured and the size of each bucket. properties: range: type: object description: The overall range the distribution covers. properties: start: type: integer description: The start of the range. example: 0 end: type: integer description: The end of the range. example: 10 multiplier: type: string description: >- The unit the range is measured in, such as `MINUTE`, `HOUR`, or `DAY`. example: MINUTE bucket: type: object description: The size of each individual bucket. properties: size: type: integer description: The number of units in each bucket. example: 1 multiplier: type: string description: The unit the bucket size is measured in. example: MINUTE 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, 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. ````