Stats API

Stats API allows you to fetch detailed campaign stats synchronized in real time. This API fetches data at the platform level and provides data for all types of campaigns.

API Endpoint

Method: POST

API Endpoint
https://api-{{0X}}.moengage.com/core-services/v1/campaign-stats

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

You can obtain the username and password details from the MoEngage Dashboard.

  1. Navigate to Settings > Account > APIs.
  2. Copy the following details:
    • Username: Under Workspace ID (earlier App ID), click the copy icon to copy the username.
    • Password: In the API keys section, click the copy icon in the Campaign report to copy the API key.
  3. Use these details to authenticate the API requests.

Request Headers

Metrics Required Sample Values Description
Content-Type Required {"Content-Type": "application/json"} Set the Content-Type header to application/json.
Authorization Required {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} This authentication is necessary to pass the request. For more information on generating the authentication header, refer to Authentication.
MOE-APPKEY Required {“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace, which should be passed in the request. You can find your MoEngage Workspace ID in the MoEngage Dashboard:

Settings -> Account -> APIs -> Workspace ID (earlier app id)

For more information, refer to Authentication.

Request Body

Metrics Required Values Description
request_id Required String This field shows the request ID created by a user. Helps to know the API calls made by the client.
campaign_ids Optional Array of strings This field shows the campaign IDs created, up to 10 max. per call
start_date Mandatory  String This field shows the start date of the campaign in YYYY-MM-DD format.
end_date Mandatory  String This field shows the campaign's end date in YYYY-MM-DD format. The days between the start and end dates should not exceed 30 days.
attribution_type Mandatory  String 

This field shows the attribution type that should be picked to show conversion stats.

  • VIEW_THROUGH
  • CLICK_THROUGH
  • IN_SESSION
  • TOTAL_CONVERSIONS
  • CLICK_CONVERSIONS
offset Optional Integer

This field shows the position of a record in a dataset.

The default value for the number of campaigns to skip is 0.

For example, set the offset to 50 to see the data from page 51.

limit Optional Integer This field shows the maximum number of campaigns displayed on a page. The default and max limit is up to 10 campaigns.
metric_type Required String

This field shows the total or unique values of all the metrics.

Supported values are:

  • TOTAL
  • UNIQUE

Response

Metrics Data Type Description
response_id String This field indicates the response ID, which is the same as the request ID passed in the payload.
total_campaigns Integer This field indicates the total number of campaigns that are requested in the payload.
current_page Integer This field indicates the current page number.
total_pages Integer This field indicates the total page. It is equal to the total campaigns, which is limited to 10 for each call and 10 to be displayed for each page.
data JSON Object This object contains the campaign stats. For more information, refer to Data.

Data

The data JSON object contains the following information:

Metrics Data Type Description
platforms String

This field indicates the platforms where the user has engaged with your communication.

Supported values are:

PUSH:

  • ANDROID
  • IOS
  • WEB
  • MWEB 
  • ALL_PLATFORMS
  • UNKNOWN

OSM:

  • WEB
  • MWEB 
  • ALL_PLATFORMS
  • UNKNOWN

All channels supported.

Note: Channels will be shown as a platform for those that don't have a platform name. For eg: EMAIL

locales JSON Object

This field indicates the details of the locales configured.

variations JSON Object

This object contains details of the variations of your locale. It has the following objects:

All Variations

The all_variations JSON object contains the following information:

Metrics Data Type Description
performance_stats JSON Object

This object shows your campaign's performance metrics.

To learn more about performance stats, click here.

conversion_goal_stats JSON Object

This object shows the conversion goal stats of your campaign.

To learn more about conversion_goal_stats, click here.

delivery_funnel JSON Object

This object shows the delivery stats if your campaign. 

To learn more about delivery stats, click here.

failure_breakdown JSON Object

This object shows the failure breakdown of your campaign. 

To learn more about failure breakdown, click here.

Global Control Group

Global controlled groups can be configured randomly or by uploading a user's list. To learn more about the Global controlled group, click here.

The global_control_group JSON object contains the following information:

Metrics Data Type Description
conversion_goal_stats JSON Object

This object shows the conversion goal stats of your campaign.

To learn more about conversion_goal_stats, click here.

delivery_funnel JSON Object

This object shows the delivery stats if your campaign. 

To learn more about delivery stats, click here.

failure_breakdown JSON Object

This object shows the failure breakdown of your campaign. 

To learn more about failure breakdown, click here.

Campaign Control Group

A campaign control group can be created by combining the user base that qualifies for the campaign. To learn more about the campaign-controlled group, click here.

The campaign_control_group JSON object contains the following information:

Metrics Data Type Description
conversion_goal_stats JSON Object

This object shows the conversion goal stats of your campaign.

To learn more about conversion_goal_stats, click here.

delivery_funnel JSON Object

This object shows the delivery stats if your campaign. 

To learn more about delivery stats, click here.

failure_breakdown JSON Object

This object shows the failure breakdown of your campaign. 

To learn more about failure breakdown, click here.

Performance Stats

The performance_stats JSON object contains the following information:

Metrics Data Type Channel Description
attempted Integer
  • Push
  • Email
  • Connector
  • SMS
  • FB Audience
  • Google Ads Audience
This field shows the number of communication attempts made from a campaign.
sent Integer
  • Push
  • Email
  • SMS
  • Connector
  • Facebook Audience
  • Cards
  • WhatsApp
This field shows the number of communications sent from a campaign.
failed Integer
  • Email
  • SMS
  • Push
  • Connector
This field shows the number of communications that failed to reach customers from a campaign.
bounced Integer Email This field shows the number of communications bounced for various reasons.
impression Integer
  • Push
  • In-app
  • OSM
  • Cards
  • Web personalization
This field shows the number of times your communication appeared to the user from your campaign.
click Integer
  • Email
  • SMS
  • In-App
  • WhatsApp
  • OSM
  • Cards
  • Web personalization
This field shows the number of times your users clicked the message from your communication.
opened Integer Email This field shows the number of communications opened by the user from your communication.
delivered Integer
  • Email
  • SMS
  • Cards
  • WhatsApp
This field shows the number of communications delivered to the customer.
read Integer WhatsApp This field shows the number of customers who read your communications 
closed_click Integer
  • In-app
  • OSM
  • Web personalization
This field shows the number of messages closed by your customers by clicking the close button from your communication.
unsubscribe Integer Email This field shows the number of customers who have unsubscribed from your email.
ctr (Click-Through rate) Double 
  • Web personalization
  • Email
  • SMS
  • In-App
  • OSM
  • Cards
  • Connector
  • WhatsApp

This field shows the click-through rates(ctr) from your communication, which indicates the conversion event performed after clicking the message.

Calculated as CTR = Clicks / Impressions

delivery_rate Double 
  • Email
  • SMS
  • Cards
  • WhatsApp
This field shows the rate of delivery of your communication to the customers.
read_rate Double WhatsApp

This field shows the message rate of your communication that your customers have read.

UniqueRead/uniqueDelivered * 100

successfully_synced Integer
  • FB Audience
  • Google Ads Audience
 
sent_rate Double
  • Connector
  • Email
  • Push
  • SMS

This field shows the rate of your communication sent to your customers 

 Sent/attempted * 100

failure_rate Double
  • Connector
  • Email
  • Push
  • SMS

This field shows the rate of failures of your communication.

(attempted-sent)/attempted * 100

eligible_users Integer
  • FB Audience
  • Google Ads Audience
This field shows the number of eligible users for your campaign.
complaint

Integer Email This field shows the count of complaints registered by your customers.
hard_bounce Integer Email This field shows the hard bounces for the Emails you sent.
soft_bounce

Integer Email This field shows the soft bounces for the Emails you sent.
open rate

Double Email This field shows the open rates of the Emails you sent.
ctor (click-trough open rate)

Double Email This field shows the click-through open rates (ctor) of the Emails you sent
unsub_rate Double Email This field shows the unsubscription rates for your Emails 
bounce_rate  Double Email This field shows the bounce_rates for the Emails you sent.
complaints_rate Double Email This field shows the complaint rates for the Emails you sent.

For more information on performance stats, refer to the following documents:

Conversion Goals

The conversion_goal_stats JSON object contains the following information:

Status Data Type Description
conversions Integer This field shows the number of conversions from your communication.
cvr (Conversion rate) Double This field shows the conversion rate for your communication.
uplift Double This field shows the percentage change in the performance metrics.

For more information on conversion goals, refer to the following documents:

Delivery Funnel

The delivery_funnel JSON object contains the following information:

Metrics Data Type Description
reachable_users_in_segment Integer This field shows the number of reachable customers in a segment.
segment_after_uninstall Integer This field shows the count of customers after uninstall.
after_fc Integer This field show the number of users obtained after removing emails that have crossed Frequency Capping as defined in the FC Settings from the After Invalid/Duplicate removal count.
users_after_dup Integer This field shows the customer count after duplication.
sent Integer This field show the count of communications you have sent 
user_devices  Integer This field shows the details of the devices used by the customer
impressions Integer This field shows the number of impressions made by your communication 
active_device_token Integer This field shows the count of active device tokens
after_invalid_removal Integer This field shows the count of customers after invalid removal.

To know more about the delivery funnel, refer to the following documents:

Failure Breakdown

The failure_breakdown JSON object contains the following information:

Metrics Data Type Channel Description

failure_breakdown

 

JSON Object
  • SMS
  • Email
  • In-App
  • OSM
  • WhatsApp
This field shows the number of communications that failed to be sent. 

For more information on failure breakdown, refer to the following documents:

 

Rate Limit

This API provides all version stats, and the call rate is limited to 100 API calls per minute or workspace.

Sample cURL Request

The following is a sample cURL with cid_list,start_date and end_date:

cURL
--location --request POST 'https://api-0X.moengage.com/core-services/v1/campaign-stats' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Authorization: Basic {{Authorization_Key}}' \--data-raw '{
"request_id": "abc",
"campaign_ids" : ["67331ed3a1893e0b12584e19", "67331ed3a1893e0b12584e20"],
"start_date" : "2024-12-22",
"end_date" : "2024-12-23",
"attribution_type": "VIEW_THROUGH",
"metric_type": "TOTAL"
}'

The following is a sample cURL with start_date and end_date but no cid_list

cURL
--location --request POST 'https://api-0X.moengage.com/core-services/v1/campaign-stats' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Authorization: Basic {{Authorization_Key}}' \--data-raw '{
"request_id": "abc",
"start_date" : "2024-12-22",
"end_date" : "2024-12-23",
"attribution_type": "VIEW_THROUGH",
"metric_type": "TOTAL"
}'

Response Codes

Status Code Request State Description

200

Successful response

This response is returned upon a successful request.

400

Bad request

Possible issues include duplicates, invalid data types, or missing mandatory attributes.

401

Unauthorized

This response is returned upon unauthorized request. Provide appropriate authentication credentials.

403

Forbidden

This response is returned when our account does not have access to the campaign stats management features. For further assistance, contact the MoEngage team.

429

Too many requests (No content)

This response is returned when the number of requests per minute has exceeded the rate limit. 

500

Internal server error

This response is returned when the system runs into an unexpected error. For further assistance, contact the MoEngage team.

Refer to the Sample Response section for examples.

Sample Response

200 200 400 401 403 429 500
{
	"response_id": "string",
    "total_campaigns": 1,
    "current_page": 1,
    "total_pages": 1,
    "data": {
        "66e933029ff25f3322d8279d": [
            {
                "platforms": {
                    "android": {
                        "locales": {
                            "all_locales": {
                                "variations": {
                                    "all_variations": {
                                        "performance_stats": {
                                            "attempted": 2,
                                            "sent": 2,
                                            "failed": 0,
                                            "impression": 2,
                                            "click": 4,
                                            "ctr": 200,
                                            "delivery_rate": 100,
                                            "sent_rate": 100,
                                            "failure_rate": 0
                                        },
                                        "conversion_goal_stats": {
                                            "Goal 1": {
				            "conversions": 0,
                       			    "cvr": 0,
                                            "uplift": 0
                                            }
                                        },
                                        "delivery_funnel": {
                                            "reachable_users_in_segment": 2,
                                            "segment_after_uninstall": 2,
                                            "after_fc": 2,
                                            "users_after_dup": 2,
                                            "sent": 2,
                                            "user_devices": 2,
                                            "impressions": 2,
                                            "active_device_token": 2
                                        },
                                        "failure_breakdown": {}
                                    },
				     "campaign_control_group": {
                                        "conversion_goal_stats": {
                                        "Goal 1": {
				        "conversions": 0,
                       		        "cvr": 0,
                                        "uplift": 0
                                            }
                                        },
                                        "delivery_funnel": {
                                            "reachable_users_in_segment": 0
                                        },
                                        "failure_breakdown": {
                                          "user_removed_due_to_campaing_control_group": 1
										}
                                    },
				   "global_control_group": {
                                        "conversion_goal_stats": {
                                            "Goal 1": {
				           "conversions": 0,
                       			   "cvr": 0,
                                           "uplift": 0
                                            }
                                        },
                                        "delivery_funnel": {
                                            "reachable_users_in_segment": 0
                                        },
                                      "failure_breakdown": {
				       "user_removed_due_to_global_control_group": 1
				       }
                                    },
                                }
                            }
                        }
                    }
                }
            }
        ]
    }
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQ

arrow_drop_down 1. What will the API response be if I pass the start date alone?

Answer: If only the start date is passed without the end date, the API will return an error response. Both the start and end dates are required to retrieve the desired response.

arrow_drop_down 2. If I pass the start and end dates without any campaign ID, will I also get the child campaign stats?

Answer: When providing the start and end dates without any campaign ID, the API will return the stats for both the parent and child campaigns. The stats will be available for the specified time period.

arrow_drop_down 3. How do we identify the stats belonging to the parent campaign in the response?

Answer: To identify the stats belonging to the parent campaign in the API response, you can use the "Campaign Details and Reachability" API. This API should be called with all the campaign IDs included in the request. The parent campaign ID field will not be available for the parent campaign, allowing you to distinguish it from the child campaigns.

arrow_drop_down 4. How can the parent-child relationship between campaigns be found?

Answer: Campaign Details and Reachability APIs will allow you to relate child campaigns to their parent campaigns.

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?