Campaign Stats and Reports Overview

Fetch real-time campaign performance statistics and download detailed campaign reports programmatically.

Overview

The MoEngage Campaign Stats and Reports API allows you to monitor your marketing performance outside of the MoEngage Dashboard. Use these endpoints to retrieve real-time platform-level statistics or generate downloadable reports for long-term analysis.

Stats & Reports API Endpoints

This suite is divided into two primary functional areas:

• Get Campaign Stats - Retrieve real-time performance metrics (clicks, impressions, conversions) at a platform level.
• Download Campaign Report - Directly download campaign data files for specified date ranges.

Comparison of Capabilities

Feature	Campaign Stats API	Campaign Report API
Data Recency	Real-time	Historical (Date Range)
Output Format	JSON	ZIP/GZIP File
Batch Limit	10 Campaigns per call	90 Days date range
Primary Use	Live Monitoring/Dashboards	Deep-dive Analysis/Audits

Technical Constraints

Rate Limits & Availability:

• Stats API: Limited to 100 requests per minute per workspace.
• Report Retention: Generated reports are available for download for 7 days before they expire.

Date Range Restrictions:

• When fetching stats, the difference between start_date and end_date must not exceed 30 days.
• When generating reports, you can request data for a maximum range of 90 days.

Authentication

Authentication methods vary between the two service types:

For Campaign Stats (Basic Auth)

Navigate to Settings > Account > APIs to find your credentials:

1. Username: Use your Workspace ID.
2. Password: Use your Campaign Report API Key.

For Campaign Reports (Header Signature)

The Report API requires a custom Signature header generated via: SHA256(Api_ID + "|" + FILENAME + "|" + SECRET_KEY)

FAQs

Campaign Statistics

How many campaigns can I query in a single Stats request?

You can pass up to 10 campaign IDs in the campaign_ids array per API call. If you need data for more campaigns, utilize the offset and limit parameters to paginate through your results.

What is the difference between TOTAL and UNIQUE metrics?

The metric_type parameter allows you to toggle your view. TOTAL counts every occurrence (e.g., three clicks by one user), while UNIQUE counts the number of distinct users who performed the action.

Can I fetch stats for a specific locale or variation?

Yes. The response object is nested by Platform > Locale > Variation, allowing you to see granular performance for A/B tests and localized content.

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

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.

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

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.

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

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.

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

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

Campaign Reports

Why did my report download fail with a 400 error?

This typically happens if the FILENAME provided is incorrect, the report was created more than 7 days ago (expired), or the APP_ID in the path does not match your credentials.

Can I fetch reports for periodic campaigns?

Yes, the Report API supports both one-time and periodic campaigns. Ensure the filename matches the specific instance you wish to download.

How do I verify if my signature implementation is correct?

Verify that your concatenation uses the pipe character (|) exactly as shown: APPID|FILENAME|SECRETKEY. Ensure the resulting string is encoded in UTF-8 before hashing with SHA256.

Why am I not receiving any response for the selected date?

Campaigns might not be available to run on the selected date to fetch the report, which could result in an error message.

Can I retrieve the report file whenever needed?

The reports generated will expire in 7 days from the date of creation.

What is the maximum number of days that I can choose to generate reports?

You can generate reports for up to 90 days.

Postman Collections

Test your integration and verify your signature logic using our Postman collection. View Postman Collection →