Amazon Pinpoint
Developer Guide

Querying Amazon Pinpoint Analytics Data

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

If you use the APIs to query analytics data, you can analyze the data by using the reporting tool of your choice, without having to sign in to the Amazon Pinpoint console or analyze raw event data from sources such as Amazon Kinesis streams. For example, you can build a custom dashboard that displays weekly campaign results or provides in-depth analytics about delivery rates for your campaigns.

You can query the data by using the Amazon Pinpoint REST API, the AWS Command Line Interface (AWS CLI), or an AWS SDK. To query the data, you send a request to the Amazon Pinpoint API and use supported parameters to specify the data that you want and any filters that you want to apply. After you submit your query, Amazon Pinpoint returns the query results in a JSON response. You can then pass the results to another service or application for deeper analysis, storage, or reporting.

Supported Metrics

Amazon Pinpoint provides programmatic access to analytics data for several 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. For example, you can use an application metric to get a breakdown of the number of messages that were opened by recipients for each campaign that's associated with a project. To access the data for an application metric, use the Application Metrics resource of the Amazon Pinpoint API.

  • Campaign metrics – These metrics provide insight into the performance of individual campaigns. For example, you can use a campaign metric to determine how many endpoints a campaign message was sent to. To access the data for a campaign metric, use the Campaign Metrics resource of the Amazon Pinpoint API.

  • Journey engagement metrics – These metrics provide insight into the performance of individual journeys. For example, you can use a journey engagement metric to get a breakdown of the number of messages that were opened by participants in each activity of a journey. To access the data for a journey engagement metric, use the Journey Engagement Metrics resource of the Amazon Pinpoint API.

  • Journey execution metrics – These metrics provide insight into participation trends for individual journeys. For example, you can use a journey execution metric to determine how many participants are proceeding through the activities in the journey. To access the data for a journey execution metric, use the Journey Execution Metrics resource of the Amazon Pinpoint API.

  • Journey activity execution metrics – These metrics provide insight into participation trends for individual activities in a journey. For example, you can use a journey activity execution metric to determine how many participants completed an activity. To access the data for a journey activity execution metric, use the Journey Activity Execution Metrics resource of the Amazon Pinpoint API.

For a complete list of standard metrics that you can query programmatically, see Standard Amazon Pinpoint Analytics Metrics.

Amazon Pinpoint automatically collects and aggregates data for all supported metrics, for all of your projects, campaigns, and journeys. In addition, the data is updated continuously, resulting in a data latency time frame that’s limited to approximately two hours. Note, however, that there may be additional data latency for certain metrics. This is because the data for some metrics is based on information that we receive from recipients' email providers. Some providers send us this information immediately, while others send it less frequently.

Amazon Pinpoint stores the data for 90 days. To store the data for more than 90 days or to access raw analytics data in real time, you can configure an Amazon Pinpoint project to stream event data to Amazon Kinesis Data Streams or Amazon Kinesis Data Firehose. For information about configuring event streams, see Streaming Amazon Pinpoint Events to Kinesis.

Query Basics

To query the data for a metric, you send a get request to the appropriate metrics resource of the Amazon Pinpoint API. In your request, you define your query by using supported parameters for the following query components:

  • Project – Specify a project by providing the project ID as the value for the application-id parameter. This parameter is required for all metrics.

  • Campaign – Specify a campaign by providing the campaign ID as the value for the campaign-id parameter. This parameter is required only for campaign metrics.

  • Journey – Specify a journey by providing the journey ID as the value for the journey-id parameter. This parameter is required only for journey engagement and execution metrics, and journey activity execution metrics.

  • Journey activity – Specify a journey activity by providing the journey activity ID as the value for the journey-activity-id parameter. This parameter is required only for journey activity execution metrics.

  • Date range – To optionally filter the data by date range, provide the first and last date and time of the date range by using supported start and end time parameters. The values should be in extended ISO 8601 format and use Coordinated Universal Time (UTC)—for example, 2019-07-19T20:00:00Z for 8:00 PM UTC July 19, 2019.

    Date ranges are inclusive and must be limited to 31 or fewer calendar days. In addition, the first date and time must be fewer than 90 days from the current day. If you don’t specify a date range, Amazon Pinpoint returns the data for the preceding 31 calendar days. Date range parameters are supported by all metrics except journey execution metrics and journey activity execution metrics.

  • Metric – Specify the metric by providing the name of the metric as the value for the kpi-name parameter. This value describes the associated metric and consists of two or more terms, which are comprised of lowercase alphanumeric characters, separated by a hyphen. Examples are email-open-rate and successful-delivery-rate. This parameter is required for all metrics except journey execution metrics and journey activity execution metrics. For a complete list of supported metrics and the kpi-name value to use for each one, see Standard Amazon Pinpoint Analytics Metrics.

After you send your query, Amazon Pinpoint returns the query results in a JSON response. In the response, the structure of the results varies depending on the metric that you queried.

Some metrics provide only one value—for example, the number of messages that were delivered by a campaign. Other metrics provide multiple values and typically group those values by a relevant field—for example, the number of messages that were delivered by each run of a campaign, grouped by campaign run. If a metric provides and groups multiple values, the JSON response includes a field that indicates which field was used to group the data. To learn more about the structure of query results, see Using Query Results.