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

cURL

Total Count

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": "total_count", "user_properties": [ { "id": "A", "property": { "action_name": "City", "executed": true, "filter_type": "user_attributes", "execution": { "count": 1, "type": "atleast" }, "attributes": { "filter_operator": "and", "filters": [] }, "pii": false, "encrypted": false }, "projection": { "data_type": "string", "extract_type": "" }, "aggregation": {} } ], "segmentation": [ { "filters": { "included_filters": { "filter_operator": "and", "filters": [ { "id": "moe_all_users", "name": "All Users", "filter_type": "custom_segments" } ] } } } ], "distribution": {}, "timerange": {}, "granularity": "e", "chart_type": "column", "count_type": "number", "split_by": [] } '

200

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

Rate Limit

The rate limits are at the workspace level. A maximum of 5 requests per second, 15 requests per minute, and 100 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 User Property Analysis (UPA) query.

version · string · required

Payload schema version.

Example:

"2.0"

type · enum<string> · required

The analysis type. Must be user_analysis for this endpoint.

Available options: user_analysis

analysis_type · enum<string> · required

The user-property computation to run — total_count (all users in scope), distinct_count (distinct values of the attribute), distribution (how users are spread across the attribute's values, using automatic or custom buckets), aggregation (sum, minimum, maximum, average, median, or percentile), or email_domain_analysis.

Available options: total_count, distinct_count, distribution, aggregation, email_domain_analysis

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

distribution · object · required

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

Show child attributes

Example:

{
  "type": "custom",
  "from": 0,
  "to": 10,
  "interval": 1
}

timerange · object · required

The time window the analysis runs over.

Show child attributes

granularity · enum<string> · required

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

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

Example:

"e"

chart_type · enum<string> · required

Visual representation of the result.

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

Example:

"column"

count_type · enum<string> · required

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

Available options: number, percentage

Example:

"number"

split_by · object[] · required

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

Maximum array length: 10

Show child attributes

Example:

[
  {
    "attr_type": "user",
    "data_type": "string",
    "encrypted": false,
    "name": "moe_ip_country",
    "pii": false,
    "readable_name": "Last Known Country"
  }
]

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