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.

承認

Authorization

string

header

必須

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.

ボディ

application/json

Request body for registering a Retention analysis query.

version

string

必須

Payload schema version.

例:

"2.0"

type

enum<string>

必須

The analysis type. Must be retention for this endpoint.

利用可能なオプション:

retention

events

object[]

必須

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[]

必須

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

必須

The time window the analysis runs over.

Show child attributes

granularity

enum<string>

必須

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.

利用可能なオプション:

h,

d,

w,

m,

e

例:

"d"

chart_type

enum<string>

必須

Visual representation of the result.

利用可能なオプション:

line,

area,

bar,

column,

euler,

pie

例:

"line"

retention_type

enum<string>

必須

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).

利用可能なオプション:

every,

last,

first

split_by

object[]

必須

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

Maximum array length: 10

Show child attributes

例:

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

comparison_timerange

object

必須

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

例:

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

レスポンス

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.

例:

"fc803857-632e-4bf0-8df1-fbc2bdeedb66"

type

string

The analysis type echoed back for the registered query.

data

object

Show child attributes

​Rate Limit

承認

ボディ

レスポンス

Rate Limit