> ## 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 Session-Source Query > Registers an asynchronous Session/Source analysis query and returns a `request_id`. Session/Source analysis reports session count or average session duration, broken down by acquisition attributes such as source, medium, and campaign. 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 50 requests per hour are allowed per workspace. ## OpenAPI ````yaml /api/analytics-query/analytics-query.yaml post /v5/analytics/session-source 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/session-source: post: tags: - Analytics Queries summary: Register a Session-Source Query description: > Registers an asynchronous Session/Source analysis query and returns a `request_id`. Session/Source analysis reports session count or average session duration, broken down by acquisition attributes such as source, medium, and campaign. 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: submitSessionSourceQuery requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionSourceQueryRequest' examples: Session Count: summary: Session count value: version: '2.0' type: session-source report_type: session_count filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 29 Days dt_label: last value: 29 comparison_timerange: {} Average Session Duration: summary: Avg. Session Duration value: version: '2.0' type: session-source report_type: average_session_duration filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 29 Days dt_label: last value: 29 comparison_timerange: {} Average Sessions Per User: summary: Avg Sessions / User value: version: '2.0' type: session-source report_type: average_session_per_user filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 29 Days dt_label: last value: 29 comparison_timerange: {} Average Conversion Per Session: summary: Avg. Conversion / Session value: version: '2.0' type: session-source report_type: average_conversion_per_session filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 7 Days dt_label: last value: 7 comparison_timerange: {} Conversion Count: summary: Conversion Count value: version: '2.0' type: session-source report_type: conversion_count filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 7 Days dt_label: last value: 7 comparison_timerange: {} Revenue: summary: Revenue value: version: '2.0' type: session-source report_type: revenue_count filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 7 Days dt_label: last value: 7 comparison_timerange: {} Bounce Rate: summary: Bounce Rate value: version: '2.0' type: session-source report_type: bounce_rate filters: [] grouped_by: [] segmentation: - filters: included_filters: filter_operator: and filters: - id: moe_all_users name: All Users filter_type: custom_segments granularity: d chart_type: line count_type: number timerange: start: '2026-07-07 00:00:00' end: '2026-07-14 23:59:59' label: Last 7 Days dt_label: last value: 7 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: 513bdf7c-951b-4e35-979d-5956488975e3 type: session-source 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: SessionSourceQueryRequest: type: object description: Request body for registering a Session/Source analysis query. required: - version - type - report_type - filters - grouped_by - segmentation - granularity - chart_type - count_type - timerange - comparison_timerange properties: version: type: string description: Payload schema version. example: '2.0' type: type: string description: The analysis type. Must be `session-source` for this endpoint. enum: - session-source report_type: type: string description: > The session metric to compute — session count, average session duration, average sessions per user, average conversions per session, conversion count, revenue, or bounce rate. enum: - session_count - average_session_duration - average_session_per_user - average_conversion_per_session - conversion_count - revenue_count - bounce_rate - avg_session_duration - no_of_users_per_session - conversion_per_session - revenue filters: type: array description: > Conditions that restrict the report to specific acquisition values. Combined with `grouped_by`, at most 2 source properties may be used. A filter value must match the attribute's declared data type. items: type: object properties: attr_type: type: string description: The category the attribute belongs to. example: source column_name: type: string description: >- The acquisition property to filter on, such as source, medium, or campaign. example: source type: type: string description: The internal type code for the attribute's data type. 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 condition: type: string description: The condition applied to the attribute. example: '&moekey is not null' example: - attr_type: source type: _s column_name: source data_types: - string encrypted: false condition: '&moekey is not null' grouped_by: type: array description: > Acquisition properties to break the report down by (for example, source and medium). Include up to 2. maxItems: 2 items: $ref: '#/components/schemas/SourceAttributeReference' example: - attr_type: source type: _s column_name: medium data_types: - string readable_name: Medium segmentation: $ref: '#/components/schemas/Segmentation' 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 timerange: $ref: '#/components/schemas/Timerange' 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-05-20 00:00:00' end: '2026-05-27 23:59:59' label: Previous quarter dt_label: prev_q 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 SourceAttributeReference: type: object description: > A reference to an acquisition attribute, such as source, medium, or campaign, used to group Session/Source results. properties: attr_type: type: string description: The category the attribute belongs to. example: source column_name: type: string description: The stored name of the acquisition attribute. example: medium readable_name: type: string description: The attribute's display name, as shown in the MoEngage dashboard. example: Medium type: type: string description: The internal type code for the attribute's data type. example: _s data_types: type: array description: The data types accepted for this attribute. items: type: string example: - string 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, 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. 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 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. ````