Amazon Pinpoint
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Querying Amazon Pinpoint Analytics Data

In addition to using the analytics pages on the Amazon Pinpoint console, you can use the Amazon Pinpoint API to query analytics data for a subset of metrics that provide insight into trends related to user engagement, campaign outreach, and more. These metrics, also referred to as a key performance indicators (KPIs), are measurable values that can help you monitor and assess the performance of your Amazon Pinpoint projects and campaigns.

By using the Amazon Pinpoint API, you can access data for two types of standard metrics:

  • Application metrics – These metrics provide insight into trends for all the campaigns and transactional messages that are associated with a project, also referred to as an application. For example, you can use an application metric to see a breakdown of the number of campaign messages that were opened by recipients for each campaign that's associated with a project.

    To query data for these metrics, you use the Application Metrics resource of the Amazon Pinpoint API. This resource represents the collection of standard application metrics that you can query by using the API.

  • Campaign metrics – These metrics provide insight into the performance of individual campaigns. For example, you can use a campaign metric to see how many endpoints a campaign message was sent to.

    To query data for these metrics, you use the Campaign Metrics resource of the Amazon Pinpoint API. This resource represents the collection of standard campaign metrics that you can query by using the API.

Amazon Pinpoint automatically collects and aggregates data for both types of metrics, and for all of your projects and campaigns. In addition, the data is updated continuously, which results in a data latency time frame that’s limited to approximately two hours. Amazon Pinpoint stores the data for 90 days.

To query the data for a metric by using the Amazon Pinpoint API, you send an HTTP GET request to the Application Metrics or Campaign Metrics URI, depending on the metric that you want to query. In your request, you define your query by using path and query parameters:

  • Project – To specify a project, provide the project ID as the value for the application-id path parameter.

  • Campaign – To specify a campaign, provide the campaign ID as the value for the campaign-id path parameter.

  • Date range – To specify a date range, provide the first and last date and time of the date range by using the start-time and end-time query parameters. The values should be in extended ISO 8601 format—for example, 2019-07-19T00:00:00Z for July 19, 2019 and 2019-07-19T20:00:00Z for 8:00 PM July 19, 2019. Date ranges are inclusive and must be limited to 31 or fewer calendar days.

  • Metric – To specify a metric, provide the name of the metric as the value for the kpi-name path parameter. For a complete list of supported metrics and the kpi-name value to use for each one, see the metrics tables later in this topic.

You can also query data by using the AWS Command Line Interface (AWS CLI). To query the data for an application metric by using the AWS CLI, use the GetApplicationDateRangeKpi command. To query the data for a campaign metric, use the GetCampaignDateRangeKpi command. When you use either command, include the preceding parameters and arguments to define your query.

After you send your query, Amazon Pinpoint returns the query results in a JSON response. Depending on the metric, the results are grouped by date, campaign ID, or another relevant field. You can then pass the results to another service or application for deeper analysis, storage, or reporting.

Application Metrics for Campaigns

The following table lists and describes standard application metrics that you can query to learn about trends for all the campaigns that are associated with an Amazon Pinpoint project. To query data for these metrics, use the Application Metrics resource of the Amazon Pinpoint API or the GetApplicationDateRangeKpi command in the AWS CLI. In the table, the kpi-name column indicates the value to use for the kpi-name parameter in your query.

Metric kpi-name Description

Delivery rate

successful-delivery-rate

For all the campaigns that are associated with a project, the percentage of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent by all the campaigns for a project and delivered to recipients, divided by the number of messages that were sent by all of those campaigns.

Delivery rate, grouped by date

successful-delivery-rate-grouped-by-date

For all the campaigns that are associated with a project, the percentage of messages that were delivered to recipients, for each day in the specified date range.

This metric is calculated as the number of messages that were sent by all the campaigns for a project and delivered to recipients, divided by the number of messages that were sent by all of those campaigns, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Email open rate

email-open-rate

For all the campaigns that are associated with a project, the percentage of email messages that were opened by recipients.

This metric is calculated as the number of email messages that were sent by all the campaigns for a project and opened by recipients, divided by the number of email messages that were sent by all of those campaigns and delivered to recipients.

Email open rate, grouped by campaign

email-open-rate-grouped-by-campaign

For each campaign that's associated with a project, the percentage of email messages that were opened by recipients.

This metric is calculated as the number of email messages that were sent by a campaign and opened by recipients, divided by the number of email messages that were sent by the campaign and delivered to recipients.

The query results for this metric are grouped by campaign ID (CampaignId), which is a string that uniquely identifies a campaign.

Endpoint deliveries

unique-deliveries

For all the campaigns that are associated with a project, the number of unique endpoints that messages were delivered to.

Endpoint deliveries, grouped by campaign

unique-deliveries-grouped-by-campaign

For each campaign that's associated with a project, the number of unique endpoints that messages were delivered to.

The query results for this metric are grouped by campaign ID (CampaignId), which is a string that uniquely identifies a campaign.

Endpoint deliveries, grouped by date

unique-deliveries-grouped-by-date

For all the campaigns that are associated with a project, the number of unique endpoints that messages were delivered to, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Messages delivered, grouped by campaign

successful-deliveries-grouped-by-campaign

For each campaign that's associated with a project, the number of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent by a campaign, minus the number of messages that were sent by the campaign and couldn't be delivered to recipients due to a hard bounce.

The query results for this metric are grouped by campaign ID (CampaignId), which is a string that uniquely identifies a campaign.

Push open rate

push-open-rate

For all the campaigns that are associated with a project, the percentage of push notifications that were opened by recipients.

This metric is calculated as the number of push notifications that were sent by all the campaigns for a project and opened by recipients, divided by the number of push notifications that were sent by all of those campaigns and delivered to recipients.

Push open rate, grouped by campaign

push-open-rate-grouped-by-campaign

For each campaign that's associated with a project, the percentage of push notifications that were opened by recipients.

This metric is calculated as the number of push notifications that were sent by a campaign and opened by recipients, divided by the number of push notifications that were sent by the campaign and delivered to recipients.

The query results for this metric are grouped by campaign ID (CampaignId), which is a string that uniquely identifies a campaign.

Application Metrics for Transactional Email Messages

The following table lists and describes standard application metrics that you can query to learn about trends for all the transactional email messages that are associated with an Amazon Pinpoint project. To query data for these metrics, use the Application Metrics resource of the Amazon Pinpoint API or the GetApplicationDateRangeKpi command in the AWS CLI. In the table, the kpi-name column indicates the value to use for the kpi-name parameter in your query.

Note that these metrics don't provide data about email messages that were sent by campaigns. They provide data about transactional email messages only. To query data for messages that were sent by one or more campaigns, use a campaign metric or an application metric for campaigns.

Metric kpi-name Description

Clicks

txn-emails-clicked

The number of times that recipients clicked links in the messages. If a single recipient clicked multiple links in a message, or clicked the same link more than once, each click is included in the count.

Clicks, grouped by date

txn-emails-clicked-grouped-by-date

The number of times that recipients clicked links in the messages, for each day in the specified date range. If a single recipient clicked multiple links in a message, or clicked the same link more than once, each click is included in the count.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Complaint rate

txn-emails-complaint-rate

The percentage of messages that were reported by recipients as unsolicited or unwanted email.

This metric is calculated as the number of messages that were reported by recipients as unsolicited or unwanted email, divided by the number of messages that were sent.

Complaint rate, grouped by date

txn-emails-complaint-rate-grouped-by-date

The percentage of messages that were reported by recipients as unsolicited or unwanted email, for each day in the specified date range.

This metric is calculated as the number of messages that were reported by recipients as unsolicited or unwanted email, divided by the number of messages that were sent, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Complaints

txn-emails-with-complaints

The number of messages that were reported by recipients as unsolicited or unwanted email.

Complaints, grouped by date

txn-emails-with-complaints-grouped-by-date

The number of messages that were reported by recipients as unsolicited or unwanted email, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Deliveries

txn-emails-delivered

The number of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent, minus the number of messages that couldn't be delivered due to a soft or hard bounce or because they were rejected. A message is rejected if Amazon Pinpoint determines that the message contains malware. Amazon Pinpoint doesn't attempt to send rejected messages.

Deliveries, grouped by date

txn-emails-delivered-grouped-by-date

The number of messages that were delivered to recipients, for each day in the specified date range.

This metric is calculated as the number of messages that were sent, minus the number of messages that couldn't be delivered due to a soft or hard bounce or because they were rejected, for each day in the specified date range. A message is rejected if Amazon Pinpoint determines that the message contains malware. Amazon Pinpoint doesn't attempt to send rejected messages.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Delivery rate

txn-emails-delivery-rate

The percentage of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent and delivered to recipients, divided by the number of messages that were sent.

Delivery rate, grouped by date

txn-emails-delivery-rate-grouped-by-date

The percentage of messages that were delivered to recipients, for each day in the specified date range.

This metric is calculated as the number of messages that were sent and delivered to recipients, divided by the number of messages that were sent, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Hard bounces

txn-emails-hard-bounced

The number of messages that couldn't be delivered to recipients due to a hard bounce. A hard bounce occurs if a persistent issue prevents a message from being delivered—for example, a recipient's email address doesn't exist.

Hard bounces, grouped by date

txn-emails-hard-bounced-grouped-by-date

The number of messages that couldn't be delivered to recipients due to a hard bounce, for each day in the specified date range. A hard bounce occurs if a persistent issue prevents a message from being delivered—for example, a recipient's email address doesn't exist.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Opens

txn-emails-opened

The number of messages that were opened by recipients.

Opens, grouped by date

txn-emails-opened-grouped-by-date

The number of messages that were opened by recipients, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Sends

txn-emails-sent

The number of messages that were sent.

Sends, grouped by date

txn-emails-sent-grouped-by-date

The number of messages that were sent, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Soft bounces

txn-emails-soft-bounced

The number of messages that couldn't be delivered to recipients due to a soft bounce. A soft bounce occurs if a temporary issue prevents a message from being delivered—for example, a recipient's inbox is full or the receiving server is temporarily unavailable.

Soft bounces, grouped by date

txn-emails-soft-bounced-grouped-by-date

The number of messages that couldn't be delivered to recipients due to a soft bounce, for each day in the specified date range. A soft bounce occurs if a temporary issue prevents a message from being delivered—for example, a recipient's inbox is full or the receiving server is temporarily unavailable.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Unique user click events

txn-emails-unique-clicks

The number of unique recipients (endpoints) who clicked links in messages.

Unlike the Clicks metric, this metric reports the number of unique recipients who clicked links, not the number of click events that occurred. For example, if a single recipient clicked multiple links in the same message, or clicked the same link more than once, this metric reports only one click event for that recipient.

Unique user click events, grouped by date

txn-emails-unique-clicks-grouped-by-date

The number of unique recipients (endpoints) who clicked links in messages, for each day in the specified date range.

Unlike the Clicks, grouped by date metric, this metric reports the number of unique recipients who clicked links, not the number of click events that occurred. For example, if a single recipient clicked multiple links in the same message, or clicked the same link more than once, this metric reports only one click event for that recipient.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Unique user open events

txn-emails-unique-opens

The number of unique recipients (endpoints) who opened messages.

Unlike the Opens metric, this metric reports the number of unique recipients who opened messages, not the number of open events that occurred. For example, if a single recipient opens the same message multiple times, this metric reports only one open event for that recipient.

Unique user open events, grouped by date

txn-emails-unique-opens-grouped-by-date

The number of unique recipients (endpoints) who opened messages, for each day in the specified date range.

Unlike the Opens, grouped by date metric, this metric reports the number of unique recipients who opened messages, not the number of open events that occurred. For example, if a single recipient opens the same message multiple times, this metric reports only one open event for that recipient.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Application Metrics for Transactional SMS Messages

The following table lists and describes standard application metrics that you can query to learn about trends for all the transactional SMS messages that are associated with an Amazon Pinpoint project. To query data for these metrics, use the Application Metrics resource of the Amazon Pinpoint API or the GetApplicationDateRangeKpi command in the AWS CLI. In the table, the kpi-name column indicates the value to use for the kpi-name parameter in your query.

Note that these metrics don't provide data about SMS messages that were sent by campaigns. They provide data about transactional SMS messages only. To query data for messages that were sent by one or more campaigns, use a campaign metric or an application metric for campaigns.

Metric kpi-name Description

Deliveries

txn-sms-delivered

The number of messages that were delivered to recipients.

Deliveries, grouped by country

txn-sms-delivered-grouped-by-country

The number of messages that were delivered to recipients, for each country or region that messages were sent to.

The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.

Deliveries, grouped by date

txn-sms-delivered-grouped-by-date

The number of messages that were delivered to recipients, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Delivery errors

txn-sms-error-distribution

The number of times that an error occurred while attempting to deliver the messages, for each type of error that occurred.

The query results for this metric are grouped by error code, for each type of error that occurred.

Delivery rate

txn-sms-delivery-rate

The percentage of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent and delivered to recipients, divided by the number of messages that were sent.

Delivery rate, grouped by date

txn-sms-delivery-rate-grouped-by-date

The percentage of messages that were delivered to recipients, for each day in the specified date range.

This metric is calculated as the number of messages that were sent and delivered to recipients, divided by the number of messages that were sent, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Sends

txn-sms-sent

The number of messages that were sent.

Sends, grouped by country

txn-sms-sent-grouped-by-country

The number of messages that were sent, for each country or region that messages were sent to.

The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.

Sends, grouped by date

txn-sms-sent-grouped-by-date

The number of messages that were sent, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Total price, grouped by country

txn-sms-total-price-grouped-by-country

The total cost, in US Dollars, of sending the messages, for each country or region that messages were sent to.

The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.

Campaign Metrics

The following table lists and describes standard campaign metrics that you can query to learn about trends for an individual campaign. To query data for these metrics, use the Campaign Metrics resource of the Amazon Pinpoint API or the GetCampaignDateRangeKpi command in the AWS CLI. In the table, the kpi-name column indicates the value to use for the kpi-name parameter in your query.

Metric kpi-name Description

Bounce rate

hard-bounce-rate

For all campaign runs, the percentage of email messages that couldn't be delivered to recipients. This metric measures only hard bounces—that is, messages in which the recipient's email address had a permanent issue that prevented the message from being delivered.

This metric is calculated as the number of bounced email messages that were sent by all the campaign runs, divided by the number of email messages that were sent by all of those campaign runs.

Bounce rate, grouped by campaign run

hard-bounce-rate-grouped-by-campaign-activity

For each campaign run, the percentage of email messages that couldn't be delivered to recipients. This metric measures only hard bounces—that is, messages in which the recipient's email address had a permanent issue that prevented the message from being delivered.

This metric is calculated as the number of bounced email messages that were sent by a campaign run, divided by the number of email messages that were sent by the campaign run.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Delivery rate

successful-delivery-rate

For all campaign runs, the percentage of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent by all the campaign runs and delivered to recipients, divided by the number of messages that were sent by all of those campaign runs.

Delivery rate, grouped by campaign run

successful-delivery-rate-grouped-by-campaign-activity

For each campaign run, the percentage of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent by a campaign run and delivered to recipients, divided by the number of messages that were sent by the campaign run.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Delivery rate, grouped by date

successful-delivery-rate-grouped-by-date

For all campaign runs, the percentage of messages that were delivered to recipients during each day in the specified date range.

This metric is calculated as the number of messages that were sent by all the campaign runs and delivered to recipients, divided by the number of messages that were sent by all of those campaign runs, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Email open rate

email-open-rate

For all campaign runs, the percentage of email messages that were opened by recipients.

This metric is calculated as the number of email messages that were sent by all the campaign runs and opened by recipients, divided by the number of email messages that were sent by all of those campaign runs and delivered to recipients.

Email open rate, grouped by campaign run

email-open-rate-grouped-by-campaign-activity

For each campaign run, the percentage of email messages that were opened by recipients.

This metric is calculated as the number of email messages that were sent by a campaign run and opened by recipients, divided by the number of email messages that were sent by the campaign run and delivered to recipients.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Emails opened, grouped by campaign run

direct-email-opens-grouped-by-campaign-activity

For each campaign run, the number of email messages that were opened by recipients.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Endpoint deliveries

unique-deliveries

For all campaign runs, the number of unique endpoints that messages were delivered to.

Endpoint deliveries, grouped by campaign run

unique-deliveries-grouped-by-campaign-activity

For each campaign run, the number of unique endpoints that messages were delivered to.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Endpoint deliveries, grouped by date

unique-deliveries-grouped-by-date

For all campaign runs, the number of unique endpoints that messages were delivered to, for each day in the specified date range.

The query results for this metric are grouped by calendar day, in extended ISO 8601 format.

Links clicked, grouped by campaign run

clicks-grouped-by-campaign-activity

For each campaign run, the number of times that recipients clicked links in the email message. If a single recipient clicked multiple links in the message, or clicked the same link more than once, each click is included in the count.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Messages delivered, grouped by campaign run

successful-deliveries-grouped-by-campaign-activity

For each campaign run, the number of messages that were delivered to recipients.

This metric is calculated as the number of messages that were sent by a campaign run, minus the number of messages that couldn't be delivered to recipients of the run due to a hard bounce.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Messages sent, grouped by campaign run

attempted-deliveries-grouped-by-campaign-activity

For each campaign run, the number of messages that were sent.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Push open rate

push-open-rate

For all campaign runs, the percentage of push notifications that were opened by recipients.

This metric is calculated as the number of push notifications that were sent by all the campaign runs and opened by recipients, divided by the number of push notifications that were sent by all of those campaign runs and delivered to recipients.

Push open rate, grouped by campaign run

push-open-rate-grouped-by-campaign-activity

For each campaign run, the percentage of push notifications that were opened by recipients.

This metric is calculated as the number of push notifications that were sent by a campaign run and opened by recipients, divided by the number of push notifications that were sent by the campaign run and delivered to recipients.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.

Total push opened, grouped by campaign run

direct-push-opens-grouped-by-campaign-activity

For each campaign run, the number of push notifications that were opened by recipients.

The query results for this metric are grouped by campaign activity ID (CampaignActivityId), which is a string that uniquely identifies a campaign run.