> ## 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 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. ## 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' example: 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 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: 6a57577219749c10af96ed2a '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: - type - analysis_type - events - segmentation - timerange - granularity 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: type: object aggregation: type: object description: Optional aggregation configuration for this event. 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: type: object distribution: type: object description: > Custom distribution configuration. When using custom buckets, include at most 10 buckets. Pass an empty object for no custom distribution. timerange: $ref: '#/components/schemas/Timerange' granularity: type: string description: > 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 chart_type: type: string description: >- Visual representation of the result, such as `line`, `column`, or `bar`. example: line count_type: type: string description: >- Whether metrics are returned as absolute counts or percentages, such as `number`. example: number chart_plot_type: type: string description: Plot scale for the chart, such as `linear`. 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: 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. 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: 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). ````