Register a Retention Query

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/retention \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "2.0",
  "type": "retention",
  "events": [
    {
      "id": "first",
      "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": []
            }
          }
        }
      ]
    },
    {
      "id": "return",
      "actions": [
        {
          "c_at_trigger_seg_v2": {
            "included_filters": {
              "filter_operator": "and",
              "filters": [
                {
                  "filter_type": "actions",
                  "action_name": "Product Viewed",
                  "execution": {
                    "count": 1,
                    "type": "atleast"
                  },
                  "executed": true,
                  "attributes": {
                    "filters": [],
                    "filter_operator": "and"
                  }
                }
              ]
            }
          },
          "c_at_act_seg_v2": {
            "included_filters": {
              "filter_operator": "and",
              "filters": []
            }
          }
        }
      ]
    }
  ],
  "segmentation": [
    {
      "filters": {
        "included_filters": {
          "filter_operator": "and",
          "filters": [
            {
              "id": "moe_all_users",
              "name": "All Users",
              "filter_type": "custom_segments"
            }
          ]
        }
      }
    }
  ],
  "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",
  "retention_type": "last",
  "split_by": [],
  "comparison_timerange": {}
}
'

{
  "response_id": "79b86153-abfc-4499-9d24-c955636d74a2",
  "type": "retention",
  "data": {
    "request_id": "REQUEST_ID"
  }
}

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

{
  "code": "ER001",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

{
  "code": "ER007",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

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

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

POST

analytics

retention

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/retention \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "2.0",
  "type": "retention",
  "events": [
    {
      "id": "first",
      "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": []
            }
          }
        }
      ]
    },
    {
      "id": "return",
      "actions": [
        {
          "c_at_trigger_seg_v2": {
            "included_filters": {
              "filter_operator": "and",
              "filters": [
                {
                  "filter_type": "actions",
                  "action_name": "Product Viewed",
                  "execution": {
                    "count": 1,
                    "type": "atleast"
                  },
                  "executed": true,
                  "attributes": {
                    "filters": [],
                    "filter_operator": "and"
                  }
                }
              ]
            }
          },
          "c_at_act_seg_v2": {
            "included_filters": {
              "filter_operator": "and",
              "filters": []
            }
          }
        }
      ]
    }
  ],
  "segmentation": [
    {
      "filters": {
        "included_filters": {
          "filter_operator": "and",
          "filters": [
            {
              "id": "moe_all_users",
              "name": "All Users",
              "filter_type": "custom_segments"
            }
          ]
        }
      }
    }
  ],
  "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",
  "retention_type": "last",
  "split_by": [],
  "comparison_timerange": {}
}
'

{
  "response_id": "79b86153-abfc-4499-9d24-c955636d74a2",
  "type": "retention",
  "data": {
    "request_id": "REQUEST_ID"
  }
}

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

{
  "code": "ER001",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

{
  "code": "ER007",
  "target": "Authentication Invalid",
  "message": "Auth validation failed."
}

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

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

Rate Limit

The rate limits are at the workspace level. A maximum of 5 requests per second, 10 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 Retention analysis query.

version

string

required

Payload schema version.

Example:

"2.0"

type

enum<string>

required

The analysis type. Must be retention for this endpoint.

Available options:

retention

events

object[]

required

Exactly two events: the first event that places a user into a cohort, and the return event measured in later periods.

Required array length: 2 elements

Show child attributes

segmentation

object[]

required

Segments to scope the analysis (up to 5). Segmentation and comparison_timerange are mutually exclusive — do not send 2 or more segments together with a time comparison.

Maximum array length: 5

Show child attributes

timerange

object

required

The time window the analysis runs over.

Show child attributes

granularity

enum<string>

required

Cohort period — h (hour), d (day), w (week), m (month), or e (entire range). Hourly is limited to a 24-hour window, daily to 90 days, and weekly to 180 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"

retention_type

enum<string>

required

The retention model to apply — every for N-Day retention (users who returned in that specific period), last for Unbounded retention (users who returned in that period or any later one), or first for First Occurrence retention (users whose first return fell in that period).

Available options:

every,

last,

first

split_by

object[]

required

Attributes to break the cohorts down by. Include up to 10.

Maximum array length: 10

Show child attributes

Example:

[
  {
    "column_name": "app_version",
    "type": "_s",
    "attr_type": "device",
    "data_types": ["string"],
    "readable_name": "App Version",
    "encrypted": false,
    "pii": false
  }
]

comparison_timerange

object

required

A second time range to compare against. Mutually exclusive with sending 2 or more segments. Pass an empty object for no comparison.

Show child attributes

Example:

{
  "start": "2026-07-20 00:00:00",
  "end": "2026-07-27 23:59:59",
  "label": "Previous month",
  "dt_label": "prev_m",
  "value": 7
}

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

​Rate Limit

Authorizations

Body

Response

Rate Limit