**End of support notice:** On October 30, 2026, AWS will end support for Amazon Pinpoint. After October 30, 2026, you will no longer be able to access the Amazon Pinpoint console or Amazon Pinpoint resources (endpoints, segments, campaigns, journeys, and analytics). For more information, see [Amazon Pinpoint end of support](https://docs.aws.amazon.com/console/pinpoint/migration-guide). **Note:** APIs related to SMS, voice, mobile push, OTP, and phone number validate are not impacted by this change and are supported by AWS End User Messaging.

# Query Amazon Pinpoint analytics data
<a name="analytics"></a>

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](event-streams.md).

## Query components and parameters for metrics in Amazon Pinpoint
<a name="analytics-query-basics"></a>

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](analytics-standard-metrics.md).

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](analytics-query-results.md).

# IAM policies for querying Amazon Pinpoint analytics data
<a name="analytics-permissions"></a>

By using the Amazon Pinpoint API, you can query analytics data for a subset of standard metrics, also referred to as *key performance indicators (KPIs)* that apply to Amazon Pinpoint projects, campaigns, and journeys. These metrics can help you monitor and assess the performance of projects, campaigns, and journeys.

To manage access to this data, you can create AWS Identity and Access Management (IAM) policies that define permissions for IAM roles or users who are authorized to access the data. To support granular control of access to this data, Amazon Pinpoint provides several distinct actions that you can specify in IAM policies. There is a distinct action for viewing analytics data on the Amazon Pinpoint console (`mobiletargeting:GetReports`), and there are other actions for accessing analytics data programmatically by using the Amazon Pinpoint API.

To create IAM policies that manage access to analytics data, you can use the AWS Management Console, the AWS CLI, or the IAM API. Note that the **Visual editor** tab on the AWS Management Console doesn’t currently include actions for viewing or querying Amazon Pinpoint analytics data. However, you can add the necessary actions to IAM policies manually by using the **JSON** tab on the console.

For example, the following policy allows programmatic access to all the analytics data for all of your projects, campaigns, and journeys in all AWS Regions:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "QueryAllAnalytics",
            "Effect": "Allow",
            "Action": [
                "mobiletargeting:GetApplicationDateRangeKpi",
                "mobiletargeting:GetCampaignDateRangeKpi",
                "mobiletargeting:GetJourneyDateRangeKpi",
                "mobiletargeting:GetJourneyExecutionMetrics",
                "mobiletargeting:GetJourneyExecutionActivityMetrics"
            ],
            "Resource": [
                "arn:aws:mobiletargeting:*:111122223333:apps/*/kpis/*",
                "arn:aws:mobiletargeting:*:111122223333:apps/*/campaigns/*/kpis/*",
                "arn:aws:mobiletargeting:*:111122223333:apps/*/journeys/*/kpis/*",
                "arn:aws:mobiletargeting:*:111122223333:apps/*/journeys/*/execution-metrics",
                "arn:aws:mobiletargeting:*:111122223333:apps/*/journeys/*/activities/*/execution-metrics"
            ]
        }
    ]
}
```

------

Where *accountId* is your AWS account ID.

However, as a best practice, you should create policies that follow the principle of *least privilege*. In other words, you should create policies that include only the permissions that are required to perform a specific task. To support this practice and implement more granular control, you can restrict programmatic access to the analytics data for only a particular project in a specific AWS Region, for example:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "QueryProjectAnalytics",
            "Effect": "Allow",
            "Action": [
                "mobiletargeting:GetApplicationDateRangeKpi",
                "mobiletargeting:GetCampaignDateRangeKpi",
                "mobiletargeting:GetJourneyDateRangeKpi",
                "mobiletargeting:GetJourneyExecutionMetrics",
                "mobiletargeting:GetJourneyExecutionActivityMetrics"
            ],
            "Resource": [
            "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/kpis/*",
    "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/campaigns/*/kpis/*",
    "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/*/kpis/*",
    "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/*/execution-metrics",
    "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/*/activities/*/execution-metrics"
            ]
        }
    ]
}
```

------

Where:
+ *region* is the name of the AWS Region that hosts the project.
+ *accountId* is your AWS account ID.
+ *projectId* is the identifier for the project that you want to provide access to.

Similarly, the following example policy allows programmatic access to the analytics data for only a particular campaign:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "QueryCampaignAnalytics",
            "Effect": "Allow",
            "Action": "mobiletargeting:GetCampaignDateRangeKpi",
            "Resource": "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/campaigns/campaignId/kpis/*"
        }
    ]
}
```

------

Where:
+ *region* is the name of the AWS Region that hosts the project.
+ *accountId* is your AWS account ID.
+ *projectId* is the identifier for the project that’s associated with the campaign.
+ *campaignId* is the identifier for the campaign that you want to provide access to.

And the following example policy allows programmatic access to all the analytics data, both engagement and execution data, for a particular journey and the activities that comprise that journey:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "QueryJourneyAnalytics",
            "Effect": "Allow",
            "Action": [
                "mobiletargeting:GetJourneyDateRangeKpi",
                "mobiletargeting:GetJourneyExecutionMetrics",
                "mobiletargeting:GetJourneyExecutionActivityMetrics"
            ],
            "Resource": [
                "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/journeyId/kpis/*",
                "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/journeyId/execution-metrics",
                "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/journeyId/activities/*/execution-metrics"
            ]
        }
    ]
}
```

------

Where:
+ *region* is the name of the AWS Region that hosts the project.
+ *accountId* is your AWS account ID.
+ *projectId* is the identifier for the project that’s associated with the journey.
+ *journeyId* is the identifier for the journey that you want to provide access to.

For a complete list of Amazon Pinpoint API actions that you can use in IAM policies, see [Amazon Pinpoint actions for IAM policies](permissions-actions.md). For detailed information about creating and managing IAM policies, see the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/).

# Standard metrics that apply to Amazon Pinpoint projects, campaigns, and journeys
<a name="analytics-standard-metrics"></a>

You can use Amazon Pinpoint Analytics APIs to query analytics data for a subset of standard metrics that apply to Amazon Pinpoint projects, campaigns, and journeys. These metrics, also referred to as a *key performance indicators (KPIs)*, are measurable values that can help you monitor and assess the performance of projects, campaigns, and journeys.

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, also referred to as an *application*. 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.
+ **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 or how many of those messages were delivered to endpoints.
+ **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.
+ **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 started a journey.
+ **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 started an activity and how many participants completed each path in an activity.

The topics in this section list and describe the individual metrics that you can query for each type of metric.

**Topics**
+ [Amazon Pinpoint application metrics for campaigns](application-metrics-campaigns.md)
+ [Amazon Pinpoint application metrics for transactional email messages](application-metrics-txn-email.md)
+ [Amazon Pinpoint application metrics for transactional SMS messages](application-metrics-txn-sms.md)
+ [Amazon Pinpoint campaign metrics](campaign-metrics.md)
+ [Amazon Pinpoint journey engagement metrics](journey-metrics-engagement-email.md)
+ [Amazon Pinpoint journey execution metrics](journey-metrics-execution.md)
+ [Amazon Pinpoint journey activity execution metrics](journey-metrics-activity-execution.md)
+ [Amazon Pinpoint journey and campaign execution metrics](journey-run-metrics-activity-execution.md)

# Amazon Pinpoint application metrics for campaigns
<a name="application-metrics-campaigns"></a>

The following table lists and describes standard application metrics that you can query to assess the performance of all the campaigns that are associated with an Amazon Pinpoint project. To query data for these metrics, use the [Application metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) resource of the Amazon Pinpoint API. The **kpi-name** column in the table indicates the value to use for the `kpi-name` parameter in a 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.  | 

# Amazon Pinpoint application metrics for transactional email messages
<a name="application-metrics-txn-email"></a>

The following table lists and describes standard application metrics that you can query to monitor 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](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) resource of the Amazon Pinpoint API. The **kpi-name** column in the table indicates the value to use for the `kpi-name` parameter in a 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](campaign-metrics.md) or an [application metric for campaigns](application-metrics-campaigns.md).


| 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, if 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, if 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, if 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, if 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.  | 

# Amazon Pinpoint application metrics for transactional SMS messages
<a name="application-metrics-txn-sms"></a>

The following table lists and describes standard application metrics that you can query to monitor 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](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) resource of the Amazon Pinpoint API. The **kpi-name** column in the table indicates the value to use for the `kpi-name` parameter in a 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](campaign-metrics.md) or an [application metric for campaigns](application-metrics-campaigns.md).


| Metric | Kpi-name | Description | 
| --- | --- | --- | 
| Average price per message, grouped by country |  `txn-sms-average-price-grouped-by-country`  |  The average cost of sending each message, for each country or region that messages were sent to. The price is shown in thousandths of a United States cent. For example, if the value of this attribute is 645, then we charged you 0.645¢ to send the message (645 / 1000 = 0.645¢ = \$10.00645). This metric is calculated as the total cost of all the messages that were sent to recipients in each country or region, divided by the number of messages that were sent to recipients in each of those countries and regions. The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.  | 
| Average price per message part, grouped by country |  `txn-sms-average-price-by-parts-grouped-by-country`  |  The average cost of sending each message part, for each country or region that messages were sent to. A message part is a portion of an SMS message. The price is shown in thousandths of a United States cent. For example, if the value of this attribute is 645, then we charged you 0.645¢ to send the message (645 / 1000 = 0.645¢ = \$10.00645). This metric is calculated as the total cost of all the message parts that were sent to recipients in each country or region, divided by the number of message parts that were sent to recipients in each of those countries and regions. The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.  | 
| 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.  | 
| Message parts delivered |  `txn-sms-delivered-by-parts`  |  The number of message parts that were delivered. A *message part* is a portion of an SMS message. If an SMS message contains more characters than the SMS protocol allows, Amazon Pinpoint splits the message into as many message parts as necessary to send the message to a recipient.  | 
| Message parts delivered, grouped by country |  `txn-sms-delivered-by-parts-grouped-by-country`  |  The number of message parts that were delivered, for each country or region that messages were sent to. A *message part* is a portion of an SMS message. The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.  | 
| Message parts sent |  `txn-sms-sent-by-parts`  |  The number of message parts that were sent. A *message part* is a portion of an SMS message. If an SMS message contains more characters than the SMS protocol allows, Amazon Pinpoint splits the message into as many message parts as necessary to send the message to a recipient.  | 
| Message parts sent, grouped by country |  `txn-sms-sent-by-parts-grouped-by-country`  |  The number of message parts that were sent, for each country or region that messages were sent to. A *message part* is a portion of an SMS message. The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.  | 
| Messages sent |  `txn-sms-sent`  | The number of messages that were sent. | 
| Messages sent, 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.  | 
| Messages sent, 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 of sending the messages, for each country or region that messages were sent to. The price is shown in thousandths of a United States cent. For example, if the value of this attribute is 645, then we charged you 0.645¢ to send the message (645 / 1000 = 0.645¢ = \$10.00645). The query results for this metric are grouped by country or region, in ISO 3166-1 alpha-2 format.  | 

# Amazon Pinpoint campaign metrics
<a name="campaign-metrics"></a>

The following table lists and describes standard campaign metrics that you can query to assess the performance of an individual campaign. To query data for these metrics, use the [Campaign metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) resource of the Amazon Pinpoint API. The **kpi-name** column in the table 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.  | 
| Total SMS spend | sms-spend | For all campaigns, the total amount of money, in milicents, spent on sending SMS. | 

# Amazon Pinpoint journey engagement metrics
<a name="journey-metrics-engagement-email"></a>

The following table lists and describes standard journey engagement metrics that you can query to monitor trends for all the email messages that were sent by an Amazon Pinpoint journey. To query data for these metrics, use the [Journey engagement metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-kpis-daterange-kpi-name.html) resource of the Amazon Pinpoint API. The **kpi-name** column in the table indicates the value to use for the `kpi-name` parameter in a query. 


| Metric | Kpi-name | Description | 
| --- | --- | --- | 
| Clicks |  `journey-emails-clicked`  |  The number of times that participants clicked links in the messages. If a single participant clicked multiple links in a message, or clicked the same link more than once, each click is included in the count.  | 
| Clicks, grouped by activity |  `emails-clicked-grouped-by-journey-activity`  |  For each activity in the journey, the number of times that participants clicked links in the messages. If a single participant 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 activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity.  | 
| Complaints |  `journey-emails-complained`  |  The number of messages that were reported by participants as unsolicited or unwanted email.   | 
| Complaints, grouped by activity |  `emails-complained-grouped-by-journey-activity`  | For each activity in the journey, the number of messages that were reported by participants as unsolicited or unwanted email.The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity. | 
| Deliveries |  `journey-emails-delivered`  |  The number of messages that were delivered to participants. 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.  | 
| Deliveries, grouped by activity |  `emails-delivered-grouped-by-journey-activity`  |  For each activity in the journey, the number of messages that were delivered to participants. 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 activity in the journey. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity.  | 
| Hard bounces |  `journey-emails-hardbounced`  |  The number of messages that couldn't be delivered to participants due to a hard bounce. A hard bounce occurs if a persistent issue prevents a message from being delivered—for example, if a participant's email address doesn't exist.  | 
| Hard bounces, grouped by activity |  `emails-hardbounced-grouped-by-journey-activity`  |  For each activity in the journey, the number of messages that couldn't be delivered to participants due to a hard bounce. A hard bounce occurs if a persistent issue prevents a message from being delivered—for example, if a participant's email address doesn't exist. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity.  | 
| Opens |  `journey-emails-opened`  |  The number of messages that were opened by participants.  | 
| Opens, grouped by activity |  `emails-opened-grouped-by-journey-activity`  |  For each activity in the journey, the number of messages that were opened by participants. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity.  | 
| Rejections | `journey-emails-rejected` | The number of messages that weren't sent to participants 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. | 
| Rejections, grouped by activity | `emails-rejected-grouped-by-journey-activity` | For each activity in the journey, the number of messages that weren't sent to participants 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. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity. | 
| Sends |  `journey-emails-sent`  |  The number of messages that were sent.  | 
| Sends, grouped by activity |  `emails-sent-grouped-by-journey-activity`  |  For each activity in the journey, the number of messages that were sent. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity.  | 
| Soft bounces |  `journey-emails-softbounced`  |  The number of messages that couldn't be delivered to participants due to a soft bounce. A soft bounce occurs if a temporary issue prevents a message from being delivered—for example, if a participant's inbox is full or the receiving server is temporarily unavailable.  | 
| Soft bounces, grouped by activity |  `emails-softbounced-grouped-by-journey-activity`  |  For each activity in the journey, the number of messages that couldn't be delivered to participants due to a soft bounce. A soft bounce occurs if a temporary issue prevents a message from being delivered—for example, if a participant's inbox is full or the receiving server is temporarily unavailable. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity.  | 
| Unsubscribes | `journey-emails-unsubscribed` |  The number of times that participants clicked unsubscribe links in the messages. If a single participant clicked the same unsubscribe link more than once, each click is included in the count.  | 
| Unsubscribes, grouped by activity | `emails-unsubscribed-grouped-by-journey-activity` | For each activity in the journey, the number of times that participants clicked unsubscribe links in the messages. If a single participant clicked the same unsubscribe link more than once, each click is included in the count. The query results for this metric are grouped by activity ID (`JourneyActivityId`), which is a string that uniquely identifies an activity. | 

# Amazon Pinpoint journey execution metrics
<a name="journey-metrics-execution"></a>

The following table lists and describes standard execution metrics that you can query to assess the status of participants in an Amazon Pinpoint journey. To query data for these metrics, use the [Journey execution metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-execution-metrics.html) resource of the Amazon Pinpoint API. The **Field** column in the table identifies the name of the field that appears in the query results for each metric. 


| Metric | Field | Description | 
| --- | --- | --- | 
|  Active participants  |  `ENDPOINT_ACTIVE`  |  The number of participants who are actively proceeding through the activities in the journey. This metric is calculated as the number of participants who started the journey, minus the number of participants who left the journey and the number of participants who were removed from the journey.   | 
|  Participant cancellations  |  `CANCELLED`  |  The number of participants who didn't complete the journey because the journey was cancelled.  | 
|  Participant departures  |  `ENDPOINT_LEFT`  |  The number of participants who left the journey.  | 
|  Participant entries  |  `ENDPOINT_ENTERED`  |  The number of participants who started the journey.  | 
|  Participant exceptions, reentry limits  |  `REENTRY_CAP_EXCEEDED`  |  The number of participants who didn't complete the journey because they would have exceeded the maximum number of times that a single participant can re-enter the journey.  | 
|  Participant exceptions, rejections  |  `ACTIVE_ENDPOINT_REJECTED`  |  The number of participants who can't start the journey because they are already active participants in the journey. A participant is rejected if they start a journey and you subsequently update their endpoint definition in a way that affects their inclusion in a segment (based on segment criteria) or the journey (based on activity conditions).  | 

# Amazon Pinpoint journey activity execution metrics
<a name="journey-metrics-activity-execution"></a>

The following table lists and describes standard execution metrics that you can query to assess the status of participants in each type of individual activity for an Amazon Pinpoint journey. To query data for these metrics, use the [Journey activity execution metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-activities-journey-activity-id-execution-metrics.html) resource of the Amazon Pinpoint API. The **Metrics** column in the table lists the fields that appear in the query results for each type of activity. It also provides a brief description of each field.


| Activity type | Metrics | 
| --- | --- | 
|  Yes/No split (`CONDITIONAL_SPLIT`)  |  The metrics are:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) Additional metrics are available for the activity on each path. For information about those metrics, see the row in this table for that type of activity.  | 
|  Holdout (`HOLDOUT`)  |  The metrics are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pinpoint/latest/developerguide/journey-metrics-activity-execution.html)  | 
| Email (`MESSAGE`) |  The metrics are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pinpoint/latest/developerguide/journey-metrics-activity-execution.html)  | 
| Multivariate split (`MULTI_CONDITIONAL_SPLIT`) |  For each path of the activity, the number of participants who proceeded to the activity on the path. The query results for this metric are grouped by path, `Branch_#` where *\$1* is the numeric identifier for a path—for example, `Branch_1` for the first path of the activity. Additional metrics are available for the activity on each path. For information about those metrics, see the row in this table for that type of activity.  | 
| Random split (`RANDOM_SPLIT`) |  For each path of the activity, the number of participants who proceeded to the activity on the path. The query results for this metric are grouped by path, `Branch_#` where *\$1* is the numeric identifier for a path—for example, `Branch_1` for the first path of the activity. Additional metrics are available for the activity on each path. For information about those metrics, see the row in this table for that type of activity.  | 
| Wait (`WAIT`) |  The metrics are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pinpoint/latest/developerguide/journey-metrics-activity-execution.html)  | 
| Contact Center (`CONTACT_CENTER`) |  The metrics are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pinpoint/latest/developerguide/journey-metrics-activity-execution.html)  | 

# Amazon Pinpoint journey and campaign execution metrics
<a name="journey-run-metrics-activity-execution"></a>

You can query standard execution metrics to assess the status of participants in each type of individual activity for an Amazon Pinpoint journey or campaign. To query data for these metrics, use the [Journey run activity execution metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-runs-run-id-activities-journey-activity-id-execution-metrics.html) or [Campaign Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) resource of the Amazon Pinpoint API. The following table lists the fields that appear in the query results for each type of activity. 


****  

| Metric Name | Applies to Journeys, Campaigns, or Both | Description | 
| --- | --- | --- | 
| ENDPOINT\$1PRODUCED | Both | The number of endpoints initially produced from the segment or event before any filtering. | 
| ENDPOINTS\$1FROM\$1USER | Both | If the customer has a user-id only segment, then all the endpoints of those users will be added. This metric measures the number of endpoints added in this way. | 
| ENDPOINT\$1OPT\$1OUT | Both | The endpoint was opted out and didn't enter the campaign or journey. | 
| ENDPOINT\$1INACTIVE | Both | The endpoint was inactive and didn't enter the campaign or journey. | 
| FILTERED\$1OUT\$1BY\$1SEGMENT | Both | Endpoint didn't match segment filters and didn't enter the campaign or journey. | 
| ENDPOINT\$1MISSING\$1ADDRESS | Both | Endpoint was missing an address and didn't enter the campaign or journey. | 
| ENDPOINT\$1MISSING\$1CHANNEL | Both | Endpoint was missing a channel and didn't enter the campaign or journey. | 
| ENDPOINT\$1MISSING\$1TIMEZONE | Both | Endpoint was missing a value for timezone and was filtered out. This only happens when a timezone value is required. | 
| ENDPOINT\$1TIMEZONE\$1MISMATCH | Both | Endpoint was in a timezone that wasn't included in the execution at that time. | 
| ENDPOINT\$1CHANNEL\$1MISMATCH | Campaigns | The campaign doesn't have a message configured for this endpoint's channel type. | 
| DUPLICATE\$1ENDPOINT | Both | Duplicate endpoints were found and de-duped. | 
| DUPLICATE\$1USER | Both | Duplicate users were found and de-duped from a user-id only segment. If they have the same user id, a metric of 1 will be emitted. | 
| PAUSED | Journeys | Removed from execution because the journey was paused. | 
| ENDED | Journeys | Removed from execution because the journey was ended. | 
| TREATMENT\$1HOLDOUT | Campaigns | This is emitted in A/B campaigns, for endpoints whose cohorts don’t match the current treatment. For example in a 50/50 A/B split, 50% of the endpoints will emit this metric for each treatment | 
| ENDPOINT\$1ESTIMATED\$1TIMEZONE | Journeys | Time zone estimation was able to estimate a time zone for the endpoint. | 

# Query Amazon Pinpoint analytics data for campaigns
<a name="analytics-query-campaigns"></a>

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 delivery and engagement trends for campaigns.

Each of these metrics is a measurable value, also referred to as a *key performance indicator (KPI)*, that can help you monitor and assess the performance of one or more campaigns. For example, you can use a metric to find out how many endpoints a campaign message was sent to, or how many of those messages were delivered to the intended endpoints.

Amazon Pinpoint automatically collects and aggregates this data for all of your campaigns. It stores the data for 90 days. If you integrated a mobile app with Amazon Pinpoint by using an AWS Mobile SDK, Amazon Pinpoint extends this support to include additional metrics, such as the percentage of push notifications that were opened by recipients. For information about integrating a mobile app, see [Integrate Amazon Pinpoint with your application](integrate.md).

If you use Amazon Pinpoint Analytics APIs to query data, you can choose various options that define the scope, data, grouping, and filters for your query. You do this by using parameters that specify the project, campaign, and metric that you want to query, in addition to any date-based filters that you want to apply. 

This topic explains and provides examples of how to choose these options and query the data for one or more campaigns.

## Prerequisites
<a name="analytics-query-campaigns-prerequisites"></a>

Before you query analytics data for one or more campaigns, it helps to gather the following information, which you use to define your query:
+ **Project ID** – The unique identifier for the project that’s associated with the campaign or campaigns. In the Amazon Pinpoint API, this value is stored in the `application-id` property. On the Amazon Pinpoint console, this value is displayed as the **Project ID** on the **All projects** page.
+ **Campaign ID** – The unique identifier for the campaign, if you want to query the data for only one campaign. In the Amazon Pinpoint API, this value is stored in the `campaign-id` property. This value is not displayed on the console.
+ **Date range** – Optionally, the first and last date and time of the date range to query data for. Date ranges are inclusive and must be limited to 31 or fewer calendar days. In addition, they must start fewer than 90 days from the current day. If you don’t specify a date range, Amazon Pinpoint automatically queries the data for the preceding 31 calendar days.
+ **Metric type** – The type of metric to query. There are two types, *application metrics* and *campaign metrics*. An *application metric* provides data for all the campaigns that are associated with a project, also referred to as an *application*. A *campaign metric* provides data for only one campaign.
+ **Metric** – The name of the metric to query—more specifically, the `kpi-name` value for the metric. For a complete list of supported metrics and the `kpi-name` value for each one, see [Standard metrics for projects, campaigns, and journeys](analytics-standard-metrics.md).

It also helps to determine whether you want to group the data by a relevant field. If you do, you can simplify your analysis and reporting by choosing a metric that’s designed to group data for you automatically. For example, Amazon Pinpoint provides several standard metrics that report the percentage of messages that were delivered to recipients of a campaign. One of these metrics automatically groups the data by date (`successful-delivery-rate-grouped-by-date`). Another metric automatically groups the data by campaign run (`successful-delivery-rate-grouped-by-campaign-activity`). A third metric simply returns a single value—the percentage of messages that were delivered to recipients by all campaign runs (`successful-delivery-rate`). 

If you can't find a standard metric that groups data the way that you want, you can develop a series of queries that return the data that you want. You can then manually break down or combine the query results into custom groups that you design.

Finally, it’s important to verify that you’re authorized to access the data that you want to query. For more information, see [IAM policies for querying Amazon Pinpoint analytics data](analytics-permissions.md).

# Query Amazon Pinpoint data for one campaign
<a name="analytics-query-campaigns-single"></a>

To query the data for one campaign, you use the [Campaign Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) API and specify values for the following required parameters:
+ **application-id** – The project ID, which is the unique identifier for the project that’s associated with the campaign. In Amazon Pinpoint, the terms *project* and *application* have the same meaning. 
+ **campaign-id** – The unique identifier for the campaign.
+ **kpi-name** – The name of the metric to query. This value describes the associated metric and consists of two or more terms, which are comprised of lowercase alphanumeric characters, separated by a hyphen. For a complete list of supported metrics and the `kpi-name` value for each one, see [Standard metrics for projects, campaigns, and journeys](analytics-standard-metrics.md).

You can also apply a filter that queries the data for a specific date range. If you don’t specify a date range, Amazon Pinpoint returns the data for the preceding 31 calendar days. To filter the data by different dates, use the supported date range parameters to specify the first and last date and time of the date range. 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.

The following examples show how to query analytics data for a campaign by using the Amazon Pinpoint REST API, the AWS CLI, and the AWS SDK for Java. You can use any supported AWS SDK to query analytics data for a campaign. The AWS CLI examples are formatted for Microsoft Windows. For Unix, Linux, and macOS, replace the caret (^) line-continuation character with a backslash (\$1).

------
#### [ REST API ]

To query analytics data for a campaign by using the Amazon Pinpoint REST API, send an HTTP(S) GET request to the [Campaign Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) URI. In the URI, specify the appropriate values for the required path parameters:

```
https://endpoint/v1/apps/application-id/campaigns/campaign-id/kpis/daterange/kpi-name
```

Where:
+ *endpoint* is the Amazon Pinpoint endpoint for the AWS Region that hosts the project associated with the campaign.
+ *application-id* is the unique identifier for the project that’s associated with the campaign.
+ *campaign-id* is the unique identifier for the campaign.
+ *kpi-name* is the `kpi-name` value for the metric to query.

All the parameters should be URL encoded.

To apply a filter that queries the data for a specific date range, append the `start-time` and `end-time` query parameters and values to the URI. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. Use an ampersand (&) to separate the parameters.

For example, the following request retrieves the number of unique endpoints that messages were delivered to, by all runs of a campaign, from July 19, 2019 through July 26, 2019:

```
https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/campaigns/80b8efd84042ff8d9c96ce2f8example/kpis/daterange/unique-deliveries?start-time=2019-07-19T00:00:00Z&end-time=2019-07-26T23:59:59Z
```

Where:
+ `pinpoint.us-east-1.amazonaws.com` is the Amazon Pinpoint endpoint for the AWS Region that hosts the project.
+ `1234567890123456789012345example` is the unique identifier for the project that’s associated with the campaign.
+ `80b8efd84042ff8d9c96ce2f8example` is the unique identifier for the campaign.
+ `unique-deliveries` is the `kpi-name` value for the *endpoint deliveries* campaign metric, which is the metric that reports the number of unique endpoints that messages were delivered to, by all runs of a campaign.
+ `2019-07-19T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-07-26T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ AWS CLI ]

To query analytics data for a campaign by using the AWS CLI, use the **get-campaign-date-range-kpi** command and specify the appropriate values for the required parameters:

```
C:\> aws pinpoint get-campaign-date-range-kpi ^
    --application-id application-id ^
    --campaign-id campaign-id ^
    --kpi-name kpi-name
```

Where:
+ *application-id* is the unique identifier for the project that’s associated with the campaign.
+ *campaign-id* is the unique identifier for the campaign.
+ *kpi-name* is the `kpi-name` value for the metric to query.

To apply a filter that queries the data for a specific date range, add the `start-time` and `end-time` parameters and values to your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of unique endpoints that messages were delivered to, by all runs of a campaign, from July 19, 2019 through July 26, 2019:

```
C:\> aws pinpoint get-campaign-date-range-kpi ^
    --application-id 1234567890123456789012345example ^
    --campaign-id 80b8efd84042ff8d9c96ce2f8example ^
    --kpi-name unique-deliveries ^
    --start-time 2019-07-19T00:00:00Z ^
    --end-time 2019-07-26T23:59:59Z
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project that’s associated with the campaign.
+ `80b8efd84042ff8d9c96ce2f8example` is the unique identifier for the campaign.
+ `unique-deliveries` is the `kpi-name` value for the *endpoint deliveries* campaign metric, which is the metric that reports the number of unique endpoints that messages were delivered to, by all runs of a campaign.
+ `2019-07-19T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-07-26T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ SDK for Java ]

To query analytics data for a campaign by using the AWS SDK for Java, use the **GetCampaignDateRangeKpiRequest** method of the [Campaign Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) API. Specify the appropriate values for the required parameters:

```
GetCampaignDateRangeKpiRequest request = new GetCampaignDateRangeKpiRequest()
        .withApplicationId("applicationId")
        .withCampaignId("campaignId")
        .withKpiName("kpiName")
```

Where:
+ *applicationId* is the unique identifier for the project that’s associated with the campaign.
+ *campaignId* is the unique identifier for the campaign.
+ *kpiName* is the `kpi-name` value for the metric to query.

To apply a filter that queries the data for a specific date range, include the `startTime` and `endTime` parameters and values in your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of unique endpoints that messages were delivered to, by all runs of a campaign, from July 19, 2019 through July 26, 2019:

```
GetCampaignDateRangeKpiRequest request = new GetCampaignDateRangeKpiRequest()
        .withApplicationId("1234567890123456789012345example")
        .withCampaignId("80b8efd84042ff8d9c96ce2f8example")
        .withKpiName("unique-deliveries")
        .withStartTime(Date.from(Instant.parse("2019-07-19T00:00:00Z")))
        .withEndTime(Date.from(Instant.parse("2019-07-26T23:59:59Z")));
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project that’s associated with the campaign.
+ `80b8efd84042ff8d9c96ce2f8example` is the unique identifier for the campaign.
+ `unique-deliveries` is the `kpi-name` value for the *endpoint deliveries* campaign metric, which is the metric that reports the number of unique endpoints that messages were delivered to, by all runs of a campaign.
+ `2019-07-19T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-07-26T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------

After you send your query, Amazon Pinpoint returns the query results in a JSON response. The structure of the results varies depending on the metric that you queried. Some metrics return only one value. For example, the *endpoint deliveries* (`unique-deliveries`) campaign metric, which is used in the preceding examples, returns one value—the number of unique endpoints that messages were delivered to, by all runs of a campaign. In this case, the JSON response is the following:

```
{
    "CampaignDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "CampaignId":"80b8efd84042ff8d9c96ce2f8example",
        "EndTime":"2019-07-26T23:59:59Z",
        "KpiName":"unique-deliveries",
        "KpiResult":{
            "Rows":[
                {
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"123.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-07-19T00:00:00Z"
    }
}
```

Other metrics return multiple values, and group the values by a relevant field. If a metric returns 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](analytics-query-results.md).

# Query Amazon Pinpoint data for multiple campaigns
<a name="analytics-query-campaigns-multiple"></a>

There are two ways to query the data for multiple campaigns. The best way depends on whether you want to query the data for campaigns that are all associated with the same project. If you do, it also depends on whether you want to query the data for all or only or subset of those campaigns.

To query the data for campaigns that are associated with different projects or for only a subset of the campaigns that are associated with the same project, the best approach is to create and run a series of individual queries, one for each campaign that you want to query the data for. The preceding section explains how to query the data for only one campaign.

To query the data for all the campaigns that are associated with the same project, you can use the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API. Specify values for the following required parameters:
+ **application-id** – The project ID, which is the unique identifier for the project. In Amazon Pinpoint, the terms *project* and *application* have the same meaning.
+ **kpi-name** – The name of the metric to query. This value describes the associated metric and consists of two or more terms, which are comprised of lowercase alphanumeric characters, separated by a hyphen. For a complete list of supported metrics and the `kpi-name` value for each one, see [Standard metrics for projects, campaigns, and journeys](analytics-standard-metrics.md).

You can also filter the data by date range. If you don’t specify a date range, Amazon Pinpoint returns the data for the preceding 31 calendar days. To filter the data by different dates, use the supported date range parameters to specify the first and last date and time of the date range. 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.

The following examples show how to query analytics data for a campaign by using the Amazon Pinpoint REST API, the AWS CLI, and the AWS SDK for Java. You can use any supported AWS SDK to query analytics data for a campaign. The AWS CLI examples are formatted for Microsoft Windows. For Unix, Linux, and macOS, replace the caret (^) line-continuation character with a backslash (\$1).

------
#### [ REST API ]

To query analytics data for multiple campaigns by using the Amazon Pinpoint REST API, send an HTTP(S) GET request to the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI. In the URI, specify the appropriate values for the required path parameters:

```
https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name
```

Where:
+ *endpoint* is the Amazon Pinpoint endpoint for the AWS Region that hosts the project associated with the campaigns.
+ *application-id* is the unique identifier for the project that’s associated with the campaigns.
+ *kpi-name* is the `kpi-name` value for the metric to query.

All the parameters should be URL encoded.

To apply a filter that retrieves the data for a specific date range, append the `start-time` and `end-time` query parameters and values to the URI. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. Use an ampersand (&) to separate the parameters.

For example, the following request retrieves the number of unique endpoints that messages were delivered to, by each of a project's campaigns, from July 19, 2019 through July 26, 2019:

```
https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/unique-deliveries-grouped-by-campaign?start-time=2019-07-19T00:00:00Z&end-time=2019-07-26T23:59:59Z
```

Where:
+ `pinpoint.us-east-1.amazonaws.com` is the Amazon Pinpoint endpoint for the AWS Region that hosts the project.
+ `1234567890123456789012345example` is the unique identifier for the project that’s associated with the campaigns.
+ `unique-deliveries-grouped-by-campaign` is the `kpi-name` value for the *endpoint deliveries, grouped by campaign* application metric, which is the metric that returns the number of unique endpoints that messages were delivered to, by each campaign.
+ `2019-07-19T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-07-26T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ AWS CLI ]

To query analytics data for multiple campaigns by using the AWS CLI, use the **get-application-date-range-kpi** command and specify the appropriate values for the required parameters:

```
C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id application-id ^
    --kpi-name kpi-name
```

Where:
+ *application-id* is the unique identifier for the project that’s associated with the campaigns.
+ *kpi-name* is the `kpi-name` value for the metric to query.

To apply a filter that retrieves the data for a specific date range, include the `start-time` and `end-time` parameters and values in your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of unique endpoints that messages were delivered to, by each of a project's campaigns, from July 19, 2019 through July 26, 2019:

```
C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id 1234567890123456789012345example ^
    --kpi-name unique-deliveries-grouped-by-campaign ^
    --start-time 2019-07-19T00:00:00Z ^
    --end-time 2019-07-26T23:59:59Z
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project that’s associated with the campaign.
+ `unique-deliveries-grouped-by-campaign` is the `kpi-name` value for the *endpoint deliveries, grouped by campaign* application metric, which is the metric that returns the number of unique endpoints that messages were delivered to, by each campaign.
+ `2019-07-19T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-07-26T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ SDK for Java ]

To query analytics data for multiple campaigns by using the AWS SDK for Java, use the **GetApplicationDateRangeKpiRequest** method of the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API. Specify the appropriate values for the required parameters:

```
GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("applicationId")
        .withKpiName("kpiName")
```

Where:
+ *applicationId* is the unique identifier for the project that’s associated with the campaigns.
+ *kpiName* is the `kpi-name` value for the metric to query.

To apply a filter that retrieves the data for a specific date range, include the `startTime` and `endTime` parameters and values in your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of unique endpoints that messages were delivered to, by each of a project's campaigns, from July 19, 2019 through July 26, 2019:

```
GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("1234567890123456789012345example")
        .withKpiName("unique-deliveries-grouped-by-campaign")
        .withStartTime(Date.from(Instant.parse("2019-07-19T00:00:00Z")))
        .withEndTime(Date.from(Instant.parse("2019-07-26T23:59:59Z")));
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project that’s associated with the campaigns.
+ `unique-deliveries-grouped-by-campaign` is the `kpi-name` value for the *endpoint deliveries, grouped by campaign* application metric, which is the metric that returns the number of unique endpoints that messages were delivered to, by each campaign.
+ `2019-07-19T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-07-26T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------

After you send your query, Amazon Pinpoint returns the query results in a JSON response. The structure of the results varies depending on the metric that you queried. Some metrics return only one value. Other metrics return multiple values, and those values are grouped by a relevant field. If a metric returns multiple values, the JSON response includes a field that indicates which field was used to group the data.

For example, the *endpoint deliveries, grouped by campaign* (`unique-deliveries-grouped-by-campaign`) application metric, which is used in the preceding examples, returns multiple values—the number of unique endpoints that messages were delivered to, for each campaign that's associated with a project. In this case, the JSON response is the following:

```
{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-07-26T23:59:59Z",
        "KpiName":"unique-deliveries-grouped-by-campaign",
        "KpiResult":{
            "Rows":[
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"80b8efd84042ff8d9c96ce2f8example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"123.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"810c7aab86d42fb2b56c8c966example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"456.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"42d8c7eb0990a57ba1d5476a3example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"789.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-07-19T00:00:00Z"
    }
}
```

In this case, the `GroupedBys` field indicates that the values are grouped by campaign ID (`CampaignId`).

To learn more about the structure of query results, see [Use JSON query results](analytics-query-results.md).

# Query Amazon Pinpoint analytics data for transactional messages
<a name="analytics-query-txn-messaging"></a>

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 delivery and engagement trends for the transactional messages that were sent for a project. 

Each of these metrics is a measurable value, also referred to as a *key performance indicator (KPI)*, that can help you monitor and assess the performance of transactional messages. For example, you can use a metric to find out how many transactional email or SMS messages you sent, or how many of those messages were delivered to recipients. Amazon Pinpoint automatically collects and aggregates this data for all the transactional email and SMS messages that you send for a project. It stores the data for 90 days.

If you use Amazon Pinpoint Analytics APIs to query data, you can choose various options that define the scope, data, grouping, and filters for your query. You do this by using parameters that specify the project and metric that you want to query, in addition to any date-based filters that you want to apply. 

This topic explains and provides examples of how to choose these options and query transactional messaging data for a project.

## Prerequisites
<a name="analytics-query-txn-messaging-prerequisites"></a>

Before you query analytics data for transactional messages, it helps to gather the following information, which you use to define your query:
+ **Project ID** – The unique identifier for the project that the messages were sent from. In the Amazon Pinpoint API, this value is stored in the `application-id` property. On the Amazon Pinpoint console, this value is displayed as the **Project ID** on the **All projects** page.
+ **Date range** – Optionally, the first and last date and time of the date range to query data for. Date ranges are inclusive and must be limited to 31 or fewer calendar days. In addition, they must start fewer than 90 days from the current day. If you don’t specify a date range, Amazon Pinpoint automatically queries the data for the preceding 31 calendar days.
+ **Metric** – The name of the metric to query—more specifically, the `kpi-name` value for the metric. For a complete list of supported metrics and the `kpi-name` value for each one, see [Standard metrics for projects, campaigns, and journeys](analytics-standard-metrics.md).

It also helps to determine whether you want to group the data by a relevant field. If you do, you can simplify your analysis and reporting by choosing a metric that’s designed to group data for you automatically. For example, Amazon Pinpoint provides several standard metrics that report the number of transactional SMS messages that were delivered to recipients. One of these metrics automatically groups the data by date (`txn-sms-delivered-grouped-by-date`). Another metric automatically groups the data by country or region (`txn-sms-delivered-grouped-by-country`). A third metric simply returns a single value—the number of messages that were delivered to recipients (`txn-sms-delivered`). If you can't find a standard metric that groups data the way that you want, you can develop a series of queries that return the data that you want. You can then manually break down or combine the query results into custom groups that you design.

Finally, it’s important to verify that you’re authorized to access the data that you want to query. For more information, see [IAM policies for querying Amazon Pinpoint analytics data](analytics-permissions.md).

# Query Amazon Pinpoint data for transactional email messages
<a name="analytics-query-txn-messaging-email"></a>

To query the data for transactional email messages that were sent for a project, you use the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API and specify values for the following required parameters:
+ **application-id** – The project ID, which is the unique identifier for the project. In Amazon Pinpoint, the terms *project* and *application* have the same meaning.
+ **kpi-name** – The name of the metric to query. This value describes the associated metric and consists of two or more terms, which are comprised of lowercase alphanumeric characters, separated by a hyphen. For a complete list of supported metrics and the `kpi-name` value for each one, see [Standard metrics for projects, campaigns, and journeys](analytics-standard-metrics.md).

You can also apply a filter that queries the data for a specific date range. If you don’t specify a date range, Amazon Pinpoint returns the data for the preceding 31 calendar days. To filter the data by different dates, use the supported date range parameters to specify the first and last date and time of the date range. The values should be in extended ISO 8601 format and use Coordinated Universal Time (UTC)—for example, `2019-09-06T20:00:00Z` for 8:00 PM UTC September 6, 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.

The following examples show how to query analytics data for transactional email messages by using the Amazon Pinpoint REST API, the AWS CLI, and the AWS SDK for Java. You can use any supported AWS SDK to query analytics data for transactional messages. The AWS CLI examples are formatted for Microsoft Windows. For Unix, Linux, and macOS, replace the caret (^) line-continuation character with a backslash (\$1).

------
#### [ REST API ]

To query analytics data for transactional email messages by using the Amazon Pinpoint REST API, send an HTTP(S) GET request to the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI. In the URI, specify the appropriate values for the required path parameters:

```
https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name
```

Where:
+ *endpoint* is the Amazon Pinpoint endpoint for the AWS Region that hosts the project.
+ *application-id* is the unique identifier for the project.
+ *kpi-name* is the `kpi-name` value for the metric to query.

All the parameters should be URL encoded.

To apply a filter that queries the data for a specific date range, append the `start-time` and `end-time` query parameters and values to the URI. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. Use an ampersand (&) to separate the parameters.

For example, the following request retrieves the number of transactional email messages that were sent for a project from September 6, 2019 through September 13, 2019:

```
https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/txn-emails-sent?start-time=2019-09-06T00:00:00Z&end-time=2019-09-13T23:59:59Z
```

Where:
+ `pinpoint.us-east-1.amazonaws.com` is the Amazon Pinpoint endpoint for the AWS Region that hosts the project.
+ `1234567890123456789012345example` is the unique identifier for the project.
+ `txn-emails-sent` is the `kpi-name` value for the *sends* application metric, which is the metric that reports the number of transactional email messages that were sent for a project.
+ `2019-09-06T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-09-13T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ AWS CLI ]

To query analytics data for transactional email messages by using the AWS CLI, use the **get-application-date-range-kpi** command, and specify the appropriate values for the required parameters:

```
C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id application-id ^
    --kpi-name kpi-name
```

Where:
+ *application-id* is the unique identifier for the project.
+ *kpi-name* is the `kpi-name` value for the metric to query.

To apply a filter that queries the data for a specific date range, add the `start-time` and `end-time` parameters and values to your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of transactional email messages that were sent for a project from September 6, 2019 through September 13, 2019:

```
C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id 1234567890123456789012345example ^
    --kpi-name txn-emails-sent ^
    --start-time 2019-09-06T00:00:00Z ^
    --end-time 2019-09-13T23:59:59Z
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project.
+ `txn-emails-sent` is the `kpi-name` value for the *sends* application metric, which is the metric that reports the number of transactional email messages that were sent for a project.
+ `2019-09-06T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-09-13T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ SDK for Java ]

To query analytics data for transactional email messages by using the AWS SDK for Java, use the **GetApplicationDateRangeKpiRequest** method of the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API. Specify the appropriate values for the required parameters:

```
GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("applicationId")
        .withKpiName("kpiName")
```

Where:
+ *applicationId* is the unique identifier for the project.
+ *kpiName* is the `kpi-name` value for the metric to query.

To apply a filter that queries the data for a specific date range, include the `startTime` and `endTime` parameters and values in your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of transactional email messages that were sent for a project from September 6, 2019 through September 13, 2019:

```
GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("1234567890123456789012345example")
        .withKpiName("txn-emails-sent")
        .withStartTime(Date.from(Instant.parse("2019-09-06T00:00:00Z")))
        .withEndTime(Date.from(Instant.parse("2019-09-13T23:59:59Z")));
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project.
+ `txn-emails-sent` is the `kpi-name` value for the *sends* application metric, which is the metric that reports the number of transactional email messages that were sent for a project.
+ `2019-09-06T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-09-13T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------

After you send your query, Amazon Pinpoint returns the query results in a JSON response. The structure of the results varies depending on the metric that you queried. Some metrics return only one value. For example, the *sends* (`txn-emails-sent`) application metric, which is used in the preceding examples, returns one value—the number of transactional email messages that were sent from a project. In this case, the JSON response is the following:

```
{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-09-13T23:59:59Z",
        "KpiName":"txn-emails-sent",
        "KpiResult":{
            "Rows":[
                {
                    "Values":[
                        {
                            "Key":"TxnEmailsSent",
                            "Type":"Double",
                            "Value":"62.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-09-06T00:00:00Z"
    }
}
```

Other metrics return multiple values and group the values by a relevant field. If a metric returns 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](analytics-query-results.md).

# Query Amazon Pinpoint data for transactional SMS messages
<a name="analytics-query-txn-messaging-sms"></a>

To query the data for transactional SMS messages that were sent for a project, you use the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API and specify values for the following required parameters:
+ **application-id** – The project ID, which is the unique identifier for the project. In Amazon Pinpoint, the terms *project* and *application* have the same meaning.
+ **kpi-name** – The name of the metric to query. This value describes the associated metric and consists of two or more terms, which are comprised of lowercase alphanumeric characters, separated by a hyphen. For a complete list of supported metrics and the `kpi-name` value for each one, see [Standard metrics for projects, campaigns, and journeys](analytics-standard-metrics.md).

You can also apply a filter that queries the data for a specific date range. If you don’t specify a date range, Amazon Pinpoint returns the data for the preceding 31 calendar days. To filter the data by different dates, use the supported date range parameters to specify the first date and time and the last date and time of the date range. The values should be in extended ISO 8601 format and use Coordinated Universal Time (UTC)—for example, `2019-09-06T20:00:00Z` for 8:00 PM UTC September 6, 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.

The following examples show how to query analytics data for transactional SMS messages by using the Amazon Pinpoint REST API, the AWS CLI, and the AWS SDK for Java. You can use any supported AWS SDK to query analytics data for transactional messages. The AWS CLI examples are formatted for Microsoft Windows. For Unix, Linux, and macOS, replace the caret (^) line-continuation character with a backslash (\$1).

------
#### [ REST API ]

To query analytics data for transactional SMS messages by using the Amazon Pinpoint REST API, send an HTTP(S) GET request to the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI. In the URI, specify the appropriate values for the required path parameters:

```
https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name
```

Where:
+ *endpoint* is the Amazon Pinpoint endpoint for the AWS Region that hosts the project.
+ *application-id* is the unique identifier for the project.
+ *kpi-name* is the `kpi-name` value for the metric to query.

All the parameters should be URL encoded.

To apply a filter that retrieves the data for a specific date range, append the `start-time` and `end-time` query parameters and values to the URI. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. Use an ampersand (&) to separate the parameters.

For example, the following request retrieves the number of transactional SMS messages that were sent each day from September 6, 2019 through September 8, 2019:

```
https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/txn-sms-sent-grouped-by-date?start-time=2019-09-06T00:00:00Z&end-time=2019-09-08T23:59:59Z
```

Where:
+ `pinpoint.us-east-1.amazonaws.com` is the Amazon Pinpoint endpoint for the AWS Region that hosts the project.
+ `1234567890123456789012345example` is the unique identifier for the project.
+ `txn-sms-sent-grouped-by-date` is the `kpi-name` value for the *sends, grouped by date* application metric, which is the metric that returns the number of transactional SMS messages that were sent during each day of the date range.
+ `2019-09-06T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-09-08T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ AWS CLI ]

To query analytics data for transactional SMS messages by using the AWS CLI, use the **get-application-date-range-kpi** command, and specify the appropriate values for the required parameters:

```
C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id application-id ^
    --kpi-name kpi-name
```

Where:
+ *application-id* is the unique identifier for the project.
+ *kpi-name* is the `kpi-name` value for the metric to query.

To apply a filter that retrieves the data for a specific date range, include the `start-time` and `end-time` parameters and values in your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of transactional SMS messages that were sent each day from September 6, 2019 through September 8, 2019:

```
C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id 1234567890123456789012345example ^
    --kpi-name txn-sms-sent-grouped-by-date ^
    --start-time 2019-09-06T00:00:00Z ^
    --end-time 2019-09-08T23:59:59Z
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project.
+ `txn-sms-sent-grouped-by-date` is the `kpi-name` value for the *sends, grouped by date* application metric, which is the metric that returns the number of transactional SMS messages that were sent during each day of the date range.
+ `2019-09-06T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-09-08T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------
#### [ SDK for Java ]

To query analytics data for transactional SMS messages by using the AWS SDK for Java, use the **GetApplicationDateRangeKpiRequest** method of the [Application Metrics](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API, and specify the appropriate values for the required parameters:

```
GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("applicationId")
        .withKpiName("kpiName")
```

Where:
+ *applicationId* is the unique identifier for the project.
+ *kpiName* is the `kpi-name` value for the metric to query.

To apply a filter that retrieves the data for a specific date range, include the `startTime` and `endTime` parameters and values in your query. By using these parameters, you can specify the first and last date and time, in extended ISO 8601 format, of an inclusive date range to retrieve the data for. For example, the following request retrieves the number of transactional SMS messages that were sent each day from September 6, 2019 through September 8, 2019:

```
GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("1234567890123456789012345example")
        .withKpiName("txn-sms-sent-grouped-by-date")
        .withStartTime(Date.from(Instant.parse("2019-09-06T00:00:00Z")))
        .withEndTime(Date.from(Instant.parse("2019-09-08T23:59:59Z")));
```

Where:
+ `1234567890123456789012345example` is the unique identifier for the project.
+ `txn-sms-sent-grouped-by-date` is the `kpi-name` value for the *sends, grouped by date* application metric, which is the metric that returns the number of transactional SMS messages that were sent during each day of the date range.
+ `2019-09-06T00:00:00Z` is the first date and time to retrieve data for, as part of an inclusive date range.
+ `2019-09-08T23:59:59Z` is the last date and time to retrieve data for, as part of an inclusive date range.

------

After you send your query, Amazon Pinpoint returns the query results in a JSON response. The structure of the results varies depending on the metric that you queried. Some metrics return only one value. Other metrics return multiple values and group those values by a relevant field. If a metric returns multiple values, the JSON response includes a field that indicates which field was used to group the data.

For example, the *sends, grouped by date* (`txn-sms-sent-grouped-by-date`) application metric, which is used in the preceding examples, returns multiple values—the number of transactional SMS messages that were sent during each day of the specified date range. In this case, the JSON response is the following:

```
{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-09-08T23:59:59Z",
        "KpiName":"txn-sms-sent-grouped-by-date",
        "KpiResult":{
            "Rows":[
                {
                    "GroupedBys":[
                        {
                            "Key":"Date",
                            "Type":"String",
                            "Value":"2019-09-06"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"TxnSmsSent",
                            "Type":"Double",
                            "Value":"29.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"Date",
                            "Type":"String",
                            "Value":"2019-09-07"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"TxnSmsSent",
                            "Type":"Double",
                            "Value":"35.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"Date",
                            "Type":"String",
                            "Value":"2019-09-08"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"TxnSmsSent",
                            "Type":"Double",
                            "Value":"10.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-09-06T00:00:00Z"
    }
}
```

In this case, the `GroupedBys` field indicates that the values are grouped by calendar day (`Date`). This means that: 
+ 29 messages were sent on September 6, 2019.
+ 35 messages were sent on September 7, 2019.
+ 10 messages were sent on September 8, 2019.

To learn more about the structure of query results, see [Use JSON query results](analytics-query-results.md).

# Use Amazon Pinpoint analytics JSON query results
<a name="analytics-query-results"></a>

When you use Amazon Pinpoint Analytics APIs to query analytics data, Amazon Pinpoint returns the results in a JSON response. For application metrics, campaign metrics, and journey engagement metrics, the data in the response adheres to a standard JSON schema for reporting Amazon Pinpoint analytics data. 

This means that you can use the programming language or tool of your choice to implement a custom solution that queries the data for one or more of these metrics, captures the results of each query, and then writes the results to a table, object, or other location. You can then work with the query results in that location by using another service or application.

For example, you can:
+ Build a custom dashboard that queries a set of metrics on a regular basis and displays the results by using your preferred data visualization framework.
+ Create a report that tracks engagement rates by querying the appropriate metrics and displaying the results in a chart or other type of report that you design.
+ Parse and write analytics data to a particular storage format, and then port the results to a long-term storage solution.

Note that Amazon Pinpoint Analytics APIs aren't designed to create or store any persistent objects that you can subsequently read or use in an Amazon Pinpoint project or your Amazon Pinpoint account. Instead, the APIs are designed to help you retrieve analytics data and transfer that data to other services and applications for further analysis, storage, or reporting. They do this partly by using the same JSON response structure and schema for all the analytics data that you can query programmatically for application metrics, campaign metrics, and journey engagement metrics.

This topic explains the structure, objects, and fields in a JSON response to a query for an application metric, campaign metric, or journey engagement metric. For information about the fields in a JSON response to a query for a journey execution metric or journey activity execution metric, see [Standard metrics that apply to Amazon Pinpoint projects, campaigns, and journeys](analytics-standard-metrics.md). 

## JSON structure
<a name="analytics-query-results-structure"></a>

To help you parse and use query results, Amazon Pinpoint Analytics APIs use the same JSON response structure for all Amazon Pinpoint analytics data that you can query programmatically for application metrics, campaign metrics, and journey engagement metrics. Each JSON response specifies the values that defined the query, such as the project ID (`ApplicationId`). The response also includes one (and only one) `KpiResult` object. The `KpiResult` object contains the overall result set for a query.

Each `KpiResult` object contains a `Rows` object. This is an array of objects that contain query results and relevant metadata about the values in those results. The structure and content of a `Rows` object has the following general characteristics:
+ Each row of query results is a separate JSON object, named `Values`, in the `Rows` object. For example, if a query returns three values, the `Rows` object contains three `Values` objects. Each `Values` object contains an individual result for the query.
+ Each column of query results is a property of the `Values` object that it applies to. The name of the column is stored in the `Key` field of the `Values` object.
+ For grouped query results, each `Values` object has an associated `GroupedBys` object. The `GroupedBys` object indicates which field was used to group the results. It also provides the grouping value for the associated `Values` object.
+ If the query results for a metric is null, the `Rows` object is empty.

Beyond these general characteristics, the structure and contents of the `Rows` object varies depending on the metric. This is because Amazon Pinpoint supports two kinds of metrics, *single-value metrics* and *multiple-value metrics*. 

A *single-value metric* provides only one cumulative value. An example is the percentage of messages that were delivered to recipients by all runs of a campaign. A *multiple-value metric* provides more than one value and groups those values by a relevant field. An example is the percentage of messages that were delivered to recipients for each run of a campaign, grouped by campaign run. 

You can quickly determine whether a metric is a single-value metric or multiple-value metric by referring to the name of the metric. If the name doesn't contain `grouped-by`, it's a single-value metric. If it does, it's a multiple-value metric. For a complete list of metrics that you can query programmatically, see [Standard metrics that apply to Amazon Pinpoint projects, campaigns, and journeys](analytics-standard-metrics.md). 

### Single-value metrics
<a name="analytics-query-results-structure-single"></a>

For a single-value metric, the `Rows` object contains a `Values` object that:
+ Specifies the friendly name of the metric that was queried.
+ Provides the value for the metric that was queried.
+ Identifies the data type of the value that was returned.

For example, the following JSON response contains the query results for a single-value metric. This metric reports the number of unique endpoints that messages were delivered to by all the campaigns that are associated with a project, from August 1, 2019 through August 31, 2019:

```
{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-08-31T23:59:59Z",
        "KpiName":"unique-deliveries",
        "KpiResult":{
            "Rows":[
                {
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"1368.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-08-01T00:00:00Z"
    }
}
```

In this example, the response indicates that all the project's campaigns delivered messages to 1,368 unique endpoints from August 1, 2019 through August 31, 2019, where:
+ `Key` is the friendly name of the metric whose value is specified in the `Value` field (`UniqueDeliveries`).
+ `Type` is the data type of the value specified in the `Value` field (`Double`).
+ `Value` is the actual value for the metric that was queried, including any filters that were applied (`1368.0`).

If the query results for a single-value metric is null (not greater than or equal to zero), the `Rows` object is empty. Amazon Pinpoint returns a null value for a metric if there isn't any data to return for the metric. For example:

```
{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"2345678901234567890123456example",
        "EndTime":"2019-08-31T23:59:59Z",
        "KpiName":"unique-deliveries",
        "KpiResult":{
            "Rows":[

            ]
        },
        "StartTime":"2019-08-01T00:00:00Z"
    }
}
```

### Multiple-value metrics
<a name="analytics-query-results-structure-multiple"></a>

The structure and contents of the `Rows` object for a multiple-value metric are mostly the same as a single-value metric. The `Rows` object for a multiple-value metric also contains a `Values` object. The `Values` object specifies the friendly name of the metric that was queried, provides the value for that metric, and identifies the data type of that value.

However, the `Rows` object for a multiple-value metric also contains one or more `GroupedBy` objects. There is one `GroupedBy` object for each `Values` object in the query results. The `GroupedBy` object indicates which field was used to group the data in the results and the data type of that field. It also indicates the grouping value for that field (for the associated `Values` object). 

For example, the following JSON response contains the query results for a multiple-value metric that reports the number of unique endpoints that messages were delivered to, for each campaign that's associated with a project, from August 1, 2019 through August 31, 2019:

```
{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-08-31T23:59:59Z",
        "KpiName":"unique-deliveries-grouped-by-campaign",
        "KpiResult":{
            "Rows":[
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"80b8efd84042ff8d9c96ce2f8example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"123.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"810c7aab86d42fb2b56c8c966example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"456.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"42d8c7eb0990a57ba1d5476a3example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"789.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-08-01T00:00:00Z"
    }
}
```

In this example, the response indicates that three of the project's campaigns delivered messages to unique endpoints from August 1, 2019 through August 31, 2019. For each of those campaigns, the breakdown of delivery counts is:
+ Campaign `80b8efd84042ff8d9c96ce2f8example` delivered messages to 123 unique endpoints.
+ Campaign `810c7aab86d42fb2b56c8c966example` delivered messages to 456 unique endpoints.
+ Campaign `42d8c7eb0990a57ba1d5476a3example` delivered messages to 789 unique endpoints.

Where the general structure of the objects and fields is:
+ `GroupedBys.Key` – The name of the property or field that stores the grouping value specified in the `GroupedBys.Value` field (`CampaignId`).
+ `GroupedBys.Type` – The data type of the value specified in the `GroupedBys.Value` field (`String`).
+ `GroupedBys.Value` – The actual value for the field that was used to group the data, as specified in the `GroupedBys.Key` field (campaign ID).
+ `Values.Key` – The friendly name of the metric whose value is specified in the `Values.Value` field (`UniqueDeliveries`).
+ `Values.Type` – The data type of the value specified in the `Values.Value` field (`Double`).
+ `Values.Value` – The actual value for the metric that was queried, including any filters that were applied.

If the query results for a multiple-value metric is null (not greater than or equal to zero) for a specific project, campaign, or other resource, Amazon Pinpoint doesn't return any objects or fields for the resource. If the query results for a multiple-value metric is null for all resources, Amazon Pinpoint returns an empty `Rows` object.

## JSON objects and fields
<a name="analytics-query-results-schema"></a>

In addition to specifying the values that defined a query, such as the project ID (`ApplicationId`), each JSON response to a query for an application metric, campaign metric, or journey engagement metric includes a `KpiResult` object. This object contains the overall result set for a query, which you can parse to send analytics data to another service or application. Each `KpiResult` object contains some or all of the following standard objects and fields, depending on the metric.


| Object or field | Description | 
| --- | --- | 
| Rows | An array of objects that contains the result set for a query. | 
| Rows.GroupedBys | For a multiple-value metric, an array of fields that defines the field and values that were used to group data in query results.  | 
| Rows.GroupedBys.Key | For a multiple-value metric, the name of the property or field that stores the value specified in the GroupedBys.Value field. | 
| Rows.GroupedBys.Type | For a multiple-value metric, the data type of the value specified in the GroupedBys.Value field. | 
| Rows.GroupedBys.Value | For a multiple-value metric, the actual value for the field that was used to group data in query results. This value correlates to an associated Values object. | 
| Rows.Values | An array of fields that contains query results. | 
| Rows.Values.Key | The friendly name of the metric that was queried. The metric's value is specified in the Values.Value field. | 
| Rows.Values.Type | The data type of the value specified in the Values.Value field. | 
| Rows.Values.Value | The actual value for the metric that was queried, including any filters that were applied. | 

 For information about the fields in a JSON response to a query for a journey execution metric or journey activity execution metric, see [Standard metrics that apply to Amazon Pinpoint projects, campaigns, and journeys](analytics-standard-metrics.md).