Register a Behavior Query

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/behavior \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "2.0",
  "type": "behavior",
  "analysis_type": "events",
  "events": [
    {
      "id": "A",
      "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": []
            }
          }
        }
      ],
      "split_by": [],
      "aggregation": {}
    }
  ],
  "segmentation": [
    {
      "filters": {
        "included_filters": {
          "filter_operator": "and",
          "filters": [
            {
              "id": "moe_all_users",
              "name": "All Users",
              "filter_type": "custom_segments"
            }
          ]
        }
      }
    }
  ],
  "user_attr_grouped_by": [],
  "distribution": {},
  "timerange": {
    "start": "2026-06-09 00:00:00",
    "end": "2026-06-16 23:59:59",
    "label": "Last 7 Days",
    "dt_label": "last",
    "value": 7
  },
  "granularity": "d",
  "chart_type": "line",
  "count_type": "number",
  "chart_plot_type": "linear",
  "rolling_value": -1,
  "user_aggregation_type": "",
  "user_aggregation_percentile": -1,
  "comparison_timerange": {},
  "chart_sort_type": "descending"
}
'

{
  "response_id": "fc803857-632e-4bf0-8df1-fbc2bdeedb66",
  "type": "behavior",
  "data": {
    "request_id": "6a57577219749c10af96ed2a"
  }
}

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

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "doc_url": "/api/analytics-query/analytics-query-overview"
  },
  "response_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

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

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

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

POST

analytics

behavior

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/behavior \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "2.0",
  "type": "behavior",
  "analysis_type": "events",
  "events": [
    {
      "id": "A",
      "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": []
            }
          }
        }
      ],
      "split_by": [],
      "aggregation": {}
    }
  ],
  "segmentation": [
    {
      "filters": {
        "included_filters": {
          "filter_operator": "and",
          "filters": [
            {
              "id": "moe_all_users",
              "name": "All Users",
              "filter_type": "custom_segments"
            }
          ]
        }
      }
    }
  ],
  "user_attr_grouped_by": [],
  "distribution": {},
  "timerange": {
    "start": "2026-06-09 00:00:00",
    "end": "2026-06-16 23:59:59",
    "label": "Last 7 Days",
    "dt_label": "last",
    "value": 7
  },
  "granularity": "d",
  "chart_type": "line",
  "count_type": "number",
  "chart_plot_type": "linear",
  "rolling_value": -1,
  "user_aggregation_type": "",
  "user_aggregation_percentile": -1,
  "comparison_timerange": {},
  "chart_sort_type": "descending"
}
'

{
  "response_id": "fc803857-632e-4bf0-8df1-fbc2bdeedb66",
  "type": "behavior",
  "data": {
    "request_id": "6a57577219749c10af96ed2a"
  }
}

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

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "doc_url": "/api/analytics-query/analytics-query-overview"
  },
  "response_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

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

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

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

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

Body

application/json

Request body for registering a Behavior analysis query.

type

enum<string>

required

The analysis type. Must be behavior for this endpoint.

Available options:

behavior

analysis_type

enum<string>

required

The behavior metric to compute — for example, events (event counts), users (users who performed the event), or a per-user aggregation.

Available options:

events,

users,

session,

aggregation,

aggregation_distribution,

total_events_per_user,

attribute_aggregation_per_user

events

object[]

required

The events to analyze. Include 1 to 10 events. Each event has an id, one or more actions (event + attribute filters), an optional split_by, and an optional aggregation.

Required array length: 1 - 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

timerange

object

required

The time window the analysis runs over.

Show child attributes

granularity

string

required

Time bucket for the series — for example, d (day), w (week), m (month), h (hour), or e (entire range). When hourly, the time range must not exceed 31 days.

Example:

"d"

version

string

Payload schema version.

Example:

"2.0"

user_attr_grouped_by

object[]

User attributes to group the results by. Include up to 10; the combined total with all split_by entries must not exceed 10.

Maximum array length: 10

distribution

object

Custom distribution configuration. When using custom buckets, include at most 10 buckets. Pass an empty object for no custom distribution.

chart_type

string

Visual representation of the result, such as line, column, or bar.

Example:

"line"

count_type

string

Whether metrics are returned as absolute counts or percentages, such as number.

Example:

"number"

chart_plot_type

string

Plot scale for the chart, such as linear.

Example:

"linear"

rolling_value

integer

Rolling-window size for the metric, or -1 when not used.

Example:

-1

user_aggregation_type

string

The per-user aggregation to apply. Empty when not using an aggregation.

Example:

""

user_aggregation_percentile

integer

Percentile to compute when user_aggregation_type is a percentile aggregation. A value from 1 to 100, or -1 when not used.

Example:

-1

comparison_timerange

object

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.

chart_sort_type

enum<string>

Sort order applied to the result series.

Available options:

ascending,

descending

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

Analytics Query APIs Overview Register a Funnels Query

⌘I