Register a User Analysis Query

Registers an asynchronous User Property Analysis (UPA) query and returns a request_id. User Property Analysis computes counts, distinct-value counts, distributions, and aggregations over user attributes for a cohort of users.

Use the request_id with Get Query Status to poll for completion, then Get Query Results to fetch the resolved series.

POST /v5/analytics/user-analysis

Register a User Analysis Query

cURL

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/analytics/user-analysis \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "2.0",
  "type": "user_analysis",
  "analysis_type": "distribution",
  "user_properties": [
    {
      "id": "A",
      "property": {
        "action_name": "u_l_a",
        "executed": true,
        "filter_type": "user_attributes",
        "execution": {
          "count": 1,
          "type": "atleast"
        },
        "attributes": {
          "filter_operator": "and",
          "filters": []
        },
        "pii": false,
        "encrypted": false
      },
      "projection": {
        "data_type": "datetime",
        "extract_type": "date"
      },
      "object_projection": {},
      "aggregation": {}
    }
  ],
  "segmentation": [
    {
      "filters": {
        "included_filters": {
          "filter_operator": "and",
          "filters": [
            {
              "id": "moe_all_users",
              "name": "All Users",
              "filter_type": "custom_segments"
            }
          ]
        }
      }
    }
  ],
  "distribution": {
    "type": "auto",
    "from": -1,
    "to": -1,
    "interval": -1
  },
  "timerange": {},
  "granularity": "e",
  "chart_type": "column",
  "count_type": "number",
  "split_by": [],
  "chart_sort_type": "descending"
}
'

200

{
  "response_id": "98fa8c1b-cb3f-4d29-b30e-d9e74dfb4adc",
  "type": "user_analysis",
  "data": {
    "request_id": "6a56220f9f22da29f1ec05f0"
  }
}

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

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "doc_url": "/api/analytics-query/analytics-query-overview"
  },
  "response_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

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

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

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

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

Body

application/json

Request body for registering a User Property Analysis (UPA) query.

type · enum<string> · required

The analysis type. Must be user_analysis for this endpoint.

Available options: user_analysis

analysis_type · string · required

The user-property computation to run, such as distribution (value distribution), a count, or an aggregation.

Example:

"distribution"

user_properties · object[] · required

The user attributes to analyze. Include 1 to 5 properties. When more than one is provided, results are cross-tabulated across them.

Required array length: 1 - 5 elements

Show child attributes

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

version · string

Payload schema version.

Example:

"2.0"

distribution · object

Distribution configuration. Custom distributions apply to numerical attributes only. Use type: auto for automatic bucketing.

timerange · object

The time window the analysis runs over.

Show child attributes

granularity · enum<string>

Time bucket for the series — h (hour), d (day), w (week), m (month), or e (entire range).

Available options: h, d, w, m, e

Example:

"e"

chart_type · string

Visual representation of the result, such as column.

Example:

"column"

count_type · string

Whether metrics are returned as absolute counts or percentages, such as number.

Example:

"number"

split_by · object[]

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

Maximum array length: 10

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