Follow

Campaign Statistics API

Campaign Statistics API

This REST API enables you to retrieve campaign metrics, which include whether the campaign is enabled or disabled, the goals achieved, the number of engaged users, the delivery schedule of a message after the campaign has launched, the filters applied to select users for the campaign, the number of messages delivered, the number of bounced messages, the number of emails blocked because of a previous bounce, reject, or spam report, and channel specific metrics.

You can retrieve metric totals or metrics by day. You can also specify a date range.

The response for the API request is text in CSV format that contains the entities exported.

 

API Request

Request URI and Header

Request URI - HTTP POST

 

To target the production environment: https://tap-nexus.appspot.com/api/campaign/statistics?env=p

To target the sandbox environment: https://tap-nexus.appspot.com/api/campaign/statistics?env=s

 

Request Header

Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings
Request Body

The body of the request must contain a single request object that contains one or more parameters specified. A request object is the top level JSON object specified when constructing a Campaign Statistics API request. The request object contains parameters to designate the campaign statistics to be retrieved. The parameters are described below.

 

Parameters
campaign_names

Optional. A list of identifiers (Group IDs) for the campaigns from which to export statistics. You must enclose the list in square brackets. For example:

"campaign_names" : [1552822282, 1559334192]

Each locale has an ID. If your campaigns use locales, be sure to provide an ID for each locale.

To find the ID for your campaign
  1. From the left navigation pane of the Kahuna application, open Manage > Campaigns in the left navigation pane.
  2. In the campaign list, click the name of your campaign to open the Campaign Details pages. The Group ID appears in a gray box at the top.
totals

Optional. A boolean indicating to export totals (true) or by-day statistics (false).

Note: Kahuna does not expect a string for the totals parameter value; do not enclose the value in quotation marks. The following example shows the correct syntax:
"totals" : false

export_old_copy

Optional. A boolean indicating to export current and old messages (true) or just current messages (false).

Note: Kahuna does not expect a string for the export_old_copy parameter value; do not enclose the value in quotation marks. The following example shows the correct syntax:
"export_old_copy" : false

from_date

Optional. A string representing the earliest date (yyyy/mm/dd) of the creation of the campaign. This is the start of the date range in which the campaign was created. If a campaign was created between from_date and to_date, all records for that campaign will be returned.

to_date Optional. A string representing the latest date (yyyy/mm/dd) of the creation of the campaign. This is the end of the date range in which the campaign was created. If a campaign was created between from_date and to_date, all records for that campaign will be returned.
number_of_records Required. The number of records to retrieve in this request. If the request times out, try a lower number. Numbers between 10000 and 25000 are most likely to be successful.If the number of records retrieved is less than the total number of records available, the HTTP header x-kahuna-cursor should be used as the cursor value in the next request. If the call times out after 60 seconds, you will get an HTTP 500 error, and should try again with a smaller value for number_of_records.
cursor

Optional. The cursor-string from the header x-kahuna-cursor for paging through large results progressively. The header is not set if the dataset is completely iterated. 

Example
 {
     "number_of_records" : 500,
     "totals" : false,
     "export_old_copy" : false,
     "campaign_names" : [1552822282, 1559334192],
     "from_date" : "2015/01/01",
     "to_date" : "2015/01/02" 
 }

API Response

For API responses that include a body, the body is in CSV format.

HTTP Response Codes

The HTTP response code returned from a request indicates the overall status of the request.

Codes  
200 Successful API call.
400

Bad request. Parsing or validating the API request failed.

401

Unauthorized. Authentication is either denied, incorrect, or missing.

409 Conflict. Not configured for the Campaign Statistics API.
500

Kahuna internal server error. The API service encountered an internal problem.

Response Body

The response body is text in CSV format that contains the entities exported. Each row corresponds to a campaign (for totals) or to a campaign and date (by time).

Campaign Metrics

Fields

channels A comma separated list of all the channels for the campaign, such as push, email, in_app, facebook.
counts_when When exporting By Day, the day for the row of metrics.
display_name The title of the campaign as seen on the All Campaigns page of the Kahuna application.
tags_str A comma-separated list of one or more string tags for the campaign.
campaign_group_id The internal unique identifier for the campaign.
campaign_type

The campaign type, such as adaptive, scheduled, trigger, or auto.

Note: Auto campaigns are lifecycle campaigns. Trigger campaigns are conversion campaigns.

schedule A JSON representation of the campaign delivery schedule. For example, {"frequency": "asap"} represents an ASAP scheduled campaign. This does not represent the start time of the campaign but the delivery schedule of a message after the campaign has launched.
enabled

True if the campaign is enabled or active.

False if the campaign is disabled or canceled.

segment The targeted segment of users for the campaign.
days_in_segment

The number of days users must be in the segment to qualify for the campaign.

Note: For lifecycle campaigns only.

goals The goals of the campaign. Typically, this is a single goal event name. If there is more than one goal, a comma-separated list is provided.
filters A JSON encoding of the filters applied to select users for this campaign.
created The time the campaign was created.
created_by The username of the campaign creator.
modified The date the campaign was last modified.
modified_by The username of the person who last modified the campaign.
stat_message_delivered The total number of messages delivered; all campaign messages A-E.
stat_message_engaged The number of engaged users; all campaign messages A-E.
stat_message_goal_achieved1 The number of primary or conversion goals achieved; all campaign messages A-E.
stat_message_goal_achieved2 The number of achieved for goal 2; all campaign messages A-E.
stat_message_goal_achieved3 The number of achieved for goal 3; all campaign messages A-E.
stat_message_goal_achieved4 The number of achieved for goal 4; all campaign messages A-E.
stat_message_goal_value1 The total revenue (if applicable) for goal 1; all campaign messages A-E.
stat_message_goal_value2 The total revenue (if applicable) for goal 2; all campaign messages A-E.
stat_message_goal_value3 The total revenue (if applicable) for goal 3, all campaign messages A-E.
stat_message_goal_value4 The total revenue (if applicable) for goal 4; all campaign messages A-E.
%stat_message_engaged_pct The engagement rate, all engaged/onboard/save over the total deliveries; all messages A-E.
%stat_message_goal_achieved_pct1 The conversion rate, goal 1 over the total deliveries; all messages A-E.
%stat_message_goal_achieved_pct2 The conversion rate, goal 2 over the total deliveries; all messages A-E.
%stat_message_goal_achieved_pct3 The conversion rate, goal 3 over the total deliveries; all messages A-E.
%stat_message_goal_achieved_pct4) The conversion rate, goal 4 over the total deliveries; all messages A-E.
stat_control_delivered The total number of virtual messages delivered for the control group.
stat_control_engaged The number of engaged users of the control group.
stat_control_goal_achieved1 The number of people in the control group that achieved goal 1.
stat_control_goal_achieved2 The number of people in the control group that achieved goal 2.
stat_control_goal_achieved3 The number of people in the control group that achieved goal 3.
stat_control_goal_achieved4 The number of people in the control group that achieved goal 4.
stat_control_goal_value1 The total revenue for goal 1 of people in the control group.
stat_control_goal_value2 The total revenue for goal 2 of people in the control group.
stat_control_goal_value3 The total revenue for goal 3 of people in the control group.
stat_control_goal_value4 The total revenue for goal 4 of people in the control group.
%stat_control_engaged_pct The engagement rate, all engaged/onboard/save over the total virtual deliveries in the control group.
%stat_control_goal_achieved_pct1 The conversion rate of goal 1 over the total virtual deliveries of the control group.
%stat_control_goal_achieved_pct2 The conversion rate of goal 2 over the total virtual deliveries of the control group.
%stat_control_goal_achieved_pct3 The conversion rate of goal 3 over the total virtual deliveries of the control group.
%stat_control_goal_achieved_pct4 The conversion rate of goal 4 over the total virtual deliveries of the control group.
%stat_control_optouts_uninstall_pct The percentage of opt-outs and uninstalls in the control group.

Metrics for Each Campaign Message (A-E or Control)

A message is designated A-E. Each metric is labeled with A-E or CONTROL. Control is a special group that receives no message.

API Responses
additional_params Additional parameters or deeplinks sent with the message.
attempted The number of attempted messages.
bounced The number of bounced messages from email.
clicks The number of clicks received for the message, email, or push.
delivered The number of pushes or emails delivered for the message for the channel.
delivered_ghost The number of ghost pushes delivered. A ghost push is a test push used to check for user uninstalls or opt-outs.
not_reachable The number of unreachable people for the message.
blocked The number of emails blocked because of a previous bounce, reject, or spam report.
opens The number of email opens achieved for the message.
email_unique_opens The number of unique email opens. For example, if a user opens the same email multiple times, this field shows only 1. If a user opens the same email four times and another user opens the same email five times, this field shows only 2.
email_unique_clicks The number of unique email clicks. For example, if a user clicks the same link in an email multiple times, this field shows only 1. If a user clicks the same link in an email four times and another user clicks the same link in the same email five times, this field shows only 2.
spam The number of spam reports from the email campaign.
email_undelivered The number of emails rejected at the time of sending.
unsubs The number of all unsubscribes for an email campaign.
ia_available The number of in-app messages available for the message.
ia_delivered The number of in-app messages delivered for the message.
ia_not_reachable The number of in-app unreachable people for the message.
message_text The message test for in-app or push, or the subject for the email channel.
missing_params The number of messages missing parameters for the message.
more_engaged The number of more engaged people for the message.
no_longer_valid The number of people who no longer meet the segment and filter criteria at the time of sending.
onboards The number of onboards for the message. An onboard is a transition of a person from the newbie segment to the engaged segment.
opt_outs The number of people opting out for the message.
provider_error All pushes dropped as a result of an unrecoverable error by the push provider for the message.
rate_limited All pushes and emails blocked because of recent prior messaging to the person.
saves All saved people: people transitioning from the dormant and passerby segment to the engaged segment.
selected The people selected to be included for the message.
selected_ghost The people selected for a ghost message for the message.
uninstalled The number of uninstalled apps for the message, before the message delivery.
unique_clicks The number of clicks received for the message, email or push.
uninstalled_ghost The number of uninstalled apps for the message, after the message delivery.
stat_delivered The total number of deliveries for the message for all channels.
stat_engaged The total number of engaged people for the message for all channels.
stat_goal_achieved1 The total achieved count for goal 1, for the message, all channels.
stat_goal_achieved2 The total achieved count for goal 2, for the message, all channels.
stat_goal_achieved3 The total achieved count for goal 3, for the message, all channels.
stat_goal_achieved4 The total Goal 4 Achieved Count (stat_goal_achieved4)
stat_goal_value1 The total goal 1 value achieved count for the message, all channels.
stat_goal_value2 The total goal 2 value achieved count for the message, all channels.
stat_goal_value3 The total goal 3 value achieved count for the message, all channels.
stat_goal_value4 The total goal 4 value achieved count for the message, all channels.
stat_optouts_value The total opt-outs count for the message, all channels.
stat_uninstalled_value The total uninstalled count for the message, all channels.
%stat_engaged_pct The total engagement rate for the message, all channels.
%stat_engaged_uplift_pct The total uplift for the message (vs control), all channels.
%stat_goal_achieved_pct1 The conversion rate for goal 1 for the message, all channels.
%stat_goal_achieved_pct2 The conversion rate for goal 2 for the message, all channels.
%stat_goal_achieved_pct3 The conversion rate for goal 3 for the message, all channels.
%stat_goal_achieved_pct4 The conversion rate for goal 4 for the message, all channels.
%stat_goal_achieved_uplift_pct1 The conversion uplift for goal 1 for the message (vs control), all channels.
%stat_goal_achieved_uplift_pct2 The conversion uplift for goal 2 for the message (vs control), all channels.
%stat_goal_achieved_uplift_pct3 The conversion uplift for goal 3 for the message (vs control), all channels.
%stat_goal_achieved_uplift_pct4 The conversion uplift for goal 4 for the message (vs control), all channels.
%stat_goal_value_uplift_pct1 The goal 1 value uplift percentage for the message (vs control), all channels.
%stat_goal_value_uplift_pct2 The goal 2 value uplift percentage for the message (vs control), all channels.
%stat_goal_value_uplift_pct3 The goal 3 value uplift percentage for the message (vs control), all channels.
%stat_goal_value_uplift_pct4 The goal 4 value uplift percentage for the message (vs control), all channels.
%stat_optouts_uninstall_pct The percentage of opt-outs and uninstalls, all channels.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments