> ## 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 Behavior Query > Registers an asynchronous Behavior analysis query and returns a `request_id`. Behavior analysis measures how many users perform one or more events over a time range, broken down by the dimensions you choose. 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 350 requests per hour are allowed per workspace. ## OpenAPI ````yaml /api/analytics-query/analytics-query.yaml post /v5/analytics/behavior 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/behavior: post: tags: - Analytics Queries summary: Register a Behavior Query description: > Registers an asynchronous Behavior analysis query and returns a `request_id`. Behavior analysis measures how many users perform one or more events over a time range, broken down by the dimensions you choose. 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: submitBehaviorQuery requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BehaviorQueryRequest' examples: Total Event: summary: Total Event value: 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: USER ENTERED FLOW execution: type: atleast count: 3 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-01 00:00:00' end: '2026-06-30 23:59:59' label: Last Month dt_label: last_m value: 29 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 Unique Users: summary: Unique Users value: version: '2.0' type: behavior analysis_type: users events: - id: A actions: - c_at_trigger_seg_v2: included_filters: filter_operator: and filters: - filter_type: actions action_name: USER ENTERED FLOW execution: type: atleast count: 3 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-01 00:00:00' end: '2026-06-30 23:59:59' label: Last Month dt_label: last_m value: 29 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 Unique Sessions: summary: Unique Sessions value: version: '2.0' type: behavior analysis_type: session events: - id: A actions: - c_at_trigger_seg_v2: included_filters: filter_operator: and filters: - filter_type: actions action_name: USER ENTERED FLOW execution: type: atleast count: 3 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-01 00:00:00' end: '2026-06-30 23:59:59' label: Last Month dt_label: last_m value: 29 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 Aggregation: summary: Aggregation value: version: '2.0' type: behavior analysis_type: aggregation events: - id: A actions: - 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: [] split_by: [] aggregation: operation: sum attr: attr_type: event column_name: quantity data_types: - double encrypted: false pii: false readable_name: quantity type: _f percentile_value: -1 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-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 count_type: number chart_plot_type: linear rolling_value: -1 user_aggregation_type: '' user_aggregation_percentile: -1 comparison_timerange: {} Aggregation Distribution - Auto: summary: Aggregation Distribution - Auto value: version: '2.0' type: behavior analysis_type: attribute_aggregation_per_user events: - id: A actions: - 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: [] split_by: [] aggregation: operation: median attr: attr_type: event column_name: amount data_types: - double encrypted: false pii: false readable_name: amount type: _f percentile_value: -1 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-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 count_type: number chart_plot_type: linear rolling_value: -1 user_aggregation_type: median user_aggregation_percentile: -1 comparison_timerange: {} Aggregation Distribution - Custom: summary: Aggregation Distribution - Custom value: version: '2.0' type: behavior analysis_type: aggregation_distribution 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: operation: sum attr: attr_type: event column_name: amount data_types: - double encrypted: false pii: false readable_name: amount type: _f percentile_value: -1 segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments user_attr_grouped_by: [] distribution: type: custom from: 0 to: 10 interval: 1 timerange: start: '2026-07-27 00:00:00' end: '2026-08-03 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 Total Events Per User: summary: Total events per user value: version: '2.0' type: behavior analysis_type: total_events_per_user events: - id: A actions: - 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: [] 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-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 count_type: number chart_plot_type: linear rolling_value: -1 user_aggregation_type: max user_aggregation_percentile: -1 comparison_timerange: {} Attribute Aggregation Per User: summary: Attribute aggregation per user value: version: '2.0' type: behavior analysis_type: aggregation_distribution events: - id: A actions: - 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: [] split_by: - attr_type: event column_name: Brand data_types: - string encrypted: false pii: false readable_name: Brand type: _s aggregation: operation: sum attr: attr_type: event column_name: quantity data_types: - double encrypted: false pii: false readable_name: quantity type: _f percentile_value: -1 segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments user_attr_grouped_by: [] distribution: type: auto from: -1 to: -1 interval: -1 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: e chart_type: line count_type: number chart_plot_type: linear rolling_value: -1 user_aggregation_type: '' user_aggregation_percentile: -1 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: fc803857-632e-4bf0-8df1-fbc2bdeedb66 type: behavior 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: BehaviorQueryRequest: type: object description: Request body for registering a Behavior analysis query. required: - version - type - analysis_type - events - segmentation - user_attr_grouped_by - distribution - timerange - granularity - chart_type - comparison_timerange properties: version: type: string description: Payload schema version. example: '2.0' type: type: string description: The analysis type. Must be `behavior` for this endpoint. enum: - behavior analysis_type: type: string description: > The behavior metric to compute — for example, `events` (event counts), `users` (users who performed the event), or a per-user aggregation. enum: - events - users - session - aggregation - aggregation_distribution - total_events_per_user - attribute_aggregation_per_user events: type: array description: > 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`. minItems: 1 maxItems: 10 items: type: object properties: id: type: string description: Identifier for the event within this query (for example, `A`). example: A 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' split_by: type: array description: > Attributes to break this event down by. The combined total of all `split_by` entries and `user_attr_grouped_by` must not exceed 10. items: $ref: '#/components/schemas/AttributeReference' aggregation: allOf: - $ref: '#/components/schemas/EventAggregation' description: > The aggregation applied to this event, used when `analysis_type` is an aggregation. Pass an empty object for other analysis types. segmentation: $ref: '#/components/schemas/Segmentation' user_attr_grouped_by: type: array description: > User attributes to group the results by. Include up to 10; the combined total with all `split_by` entries must not exceed 10. maxItems: 10 items: $ref: '#/components/schemas/AttributeReference' example: - attr_type: user column_name: t_rev data_types: - double encrypted: false pii: false readable_name: LTV type: _f distribution: allOf: - $ref: '#/components/schemas/BucketDistribution' description: > Custom distribution configuration. When using custom buckets, include at most 10 buckets. Pass an empty object for no custom distribution. example: type: custom from: 0 to: 10 interval: 1 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: d chart_type: type: string description: Visual representation of the result. enum: - line - area - bar - column - euler - pie example: line count_type: type: string description: > Whether metrics are returned as absolute counts (`number`) or as percentages (`percentage`). enum: - number - percentage example: number chart_plot_type: type: string description: Plot scale applied to the chart. enum: - linear - logarithmic - cumulative - rolling_sum - rolling_avg - rolling_window example: linear rolling_value: type: integer description: Rolling-window size for the metric, or -1 when not used. example: -1 user_aggregation_type: type: string description: >- The per-user aggregation to apply. Empty when not using an aggregation. example: '' user_aggregation_percentile: type: integer description: > 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: 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-19 00:00:00' end: '2026-08-26 23:59:59' label: Previous day dt_label: prev_d value: 7 chart_sort_type: type: string description: Sort order applied to the result series. enum: - ascending - descending 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 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 EventAggregation: type: object description: > The aggregation applied to a numeric event attribute, such as a sum or a percentile. properties: operation: type: string description: >- The aggregation to compute, such as `sum`, `min`, `max`, `average`, `median`, or a percentile. example: sum attr: allOf: - $ref: '#/components/schemas/AttributeReference' description: The attribute the aggregation is computed over. percentile_value: type: integer description: > The percentile to compute, from 1 to 100, when `operation` is a percentile. Use -1 for all other operations. example: -1 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' BucketDistribution: type: object description: > Bucketing configuration for a distribution analysis. Use `auto` to let MoEngage choose the buckets, or `custom` to define your own range and interval. properties: type: type: string description: Whether buckets are chosen automatically or defined by you. enum: - auto - custom example: custom from: type: integer description: The lower bound of the first bucket. Use -1 when `type` is `auto`. example: 0 to: type: integer description: The upper bound of the last bucket. Use -1 when `type` is `auto`. example: 10 interval: type: integer description: The width of each bucket. Use -1 when `type` is `auto`. example: 1 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. ````