Register a Funnels Query

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/funnels \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'

{
  "response_id": "498b1a8f-027b-4aba-b71e-2f6fac76deba",
  "type": "funnel",
  "data": {
    "request_id": "REQUEST_ID"
  }
}

{
  "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"
}

{
  "code": "ER001",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

{
  "code": "ER007",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

{
  "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"
}

{
  "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"
}

POST

analytics

funnels

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/funnels \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'

{
  "response_id": "498b1a8f-027b-4aba-b71e-2f6fac76deba",
  "type": "funnel",
  "data": {
    "request_id": "REQUEST_ID"
  }
}

{
  "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"
}

{
  "code": "ER001",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

{
  "code": "ER007",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

{
  "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"
}

{
  "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"
}

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.

Authorizations

Authorization

string

header

required

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 for details on creating and managing API keys.

Body

application/json

Request body for registering a Funnels analysis query.

version

string

required

Payload schema version.

Example:

"2.0"

type

enum<string>

required

The analysis type. Must be funnel for this endpoint.

Available options:

funnel

events

object[]

required

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.

Required array length: 2 - 10 elements

Show child attributes

segmentation

object[]

required

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.

Maximum array length: 5

Show child attributes

funnel_type

enum<string>

required

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).

Available options:

user_funnel,

event_funnel,

user_time_to_convert,

event_time_to_convert,

user_frequency,

event_frequency

grouped_by

object[]

required

Event attributes to split the funnel by. Include up to 3. Each item names the attribute to split on.

Maximum array length: 3

Show child attributes

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

object

required

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.

Show child attributes

Example:

{ "type": "all_steps", "applied_on": -1 }

holding_attributes

object[]

required

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.

Maximum array length: 3

Show child attributes

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

object

required

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.

Show child attributes

Example:

{ "type": "all_steps", "applied_on": -1 }

funnel_window

integer

required

The conversion window in seconds within which users must complete the funnel.

Example:

86400

funnel_window_multiplier

integer

required

Multiplier applied to the funnel window.

Example:

86400

distribution

object

required

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.

Show child attributes

Example:

{
  "method": "custom",
  "from_step": 1,
  "to_step": 2,
  "parameters": {
    "range": {
      "start": 0,
      "end": 10,
      "multiplier": "MINUTE"
    },
    "bucket": { "size": 1, "multiplier": "MINUTE" }
  }
}

chart_type

enum<string>

required

Visual representation of the result.

Available options:

line,

area,

bar,

column,

euler,

pie

Example:

"column"

comparison_timerange

object

required

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.

Show child attributes

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

object

required

The time window the analysis runs over.

Show child attributes

granularity

enum<string>

required

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.

Available options:

h,

d,

w,

m,

e

Example:

"e"

strict_order

boolean

Whether steps must be performed in the exact order defined.

Example:

false

countType

enum<string>

Whether metrics are returned as absolute counts (number) or as percentages (percentage).

Available options:

number,

percentage

Example:

"number"

showConversionEventOnly

boolean

Whether to return only the conversion event's metrics.

Example:

false

chart_plot_type

enum<string>

Plot scale applied to the chart.

Available options:

linear,

logarithmic,

cumulative,

rolling_sum,

rolling_avg,

rolling_window

Example:

"linear"

Response

Query registered. Poll status and fetch results with data.request_id.

Acknowledgement that a query was registered. Use data.request_id to poll status and fetch results.

response_id

string

A unique identifier for the response, useful for correlating logs and support requests.

Example:

"fc803857-632e-4bf0-8df1-fbc2bdeedb66"

type

string

The analysis type echoed back for the registered query.

data

object

Show child attributes

​Rate Limit

Authorizations

Body

Response

Rate Limit