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 to poll for completion, then Get Query Results to fetch the resolved series.

POST /v5/analytics/session-source

cURL

Session Count

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

200

{
  "response_id": "513bdf7c-951b-4e35-979d-5956488975e3",
  "type": "session-source",
  "data": {
    "request_id": "REQUEST_ID"
  }
}

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.

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 Session/Source analysis query.

version · string · required

Payload schema version.

Example:

"2.0"

type · enum<string> · required

The analysis type. Must be session-source for this endpoint.

Available options: session-source

report_type · enum<string> · required

The session metric to compute — session count, average session duration, average sessions per user, average conversions per session, conversion count, revenue, or bounce rate.

Available options: 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 · object[] · required

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.

Show child attributes

Example:

[
  {
    "attr_type": "source",
    "type": "_s",
    "column_name": "source",
    "data_types": ["string"],
    "encrypted": false,
    "condition": "&moekey is not null"
  }
]

grouped_by · object[] · required

Acquisition properties to break the report down by (for example, source and medium). Include up to 2.

Maximum array length: 2

Show child attributes

Example:

[
  {
    "attr_type": "source",
    "type": "_s",
    "column_name": "medium",
    "data_types": ["string"],
    "readable_name": "Medium"
  }
]

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

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:

"d"

chart_type · enum<string> · required

Visual representation of the result.

Available options: line, area, bar, column, euler, pie

Example:

"line"

count_type · enum<string> · required

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

Available options: number, percentage

Example:

"number"

timerange · object · required

The time window the analysis runs over.

Show child attributes

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-05-20 00:00:00",
  "end": "2026-05-27 23:59:59",
  "label": "Previous quarter",
  "dt_label": "prev_q",
  "value": 7
}

chart_sort_type · enum<string>

Sort order applied to the result series.

Available options: ascending, descending

Response

200

application/json

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