Query Amazon Pinpoint analytics data - Amazon Pinpoint
Query for metrics in Amazon Pinpoint

Query 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.

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 Data Firehose. For information about configuring event streams, see Stream app event data through Kinesis and Firehose using Amazon Pinpoint.

Query components and parameters for metrics in Amazon Pinpoint

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 metrics for projects, campaigns, and journeys.

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 Use JSON query results.