# GetKeyLastUsage
<a name="API_GetKeyLastUsage"></a>

Returns usage information about the last successful cryptographic operation performed with a specified KMS key, including the operation type, timestamp, and associated AWS CloudTrail event ID.

The `TrackingStartDate` in the `GetKeyLastUsage` response indicates the date from which AWS KMS began recording cryptographic activity for a given key. Use this value together with `KeyCreationDate` to understand the key's usage history:
+ If the `KeyLastUsage` response element is *present*, the key has been used for a successful cryptographic operation since the `TrackingStartDate`. The response includes the operation type, timestamp, and associated CloudTrail event ID.
+ If the `KeyLastUsage` response element is *empty* and `KeyCreationDate` is on or after `TrackingStartDate`, the key has not been used for a successful cryptographic operation since it was created.
+ If the `KeyLastUsage` response element is *empty* and `KeyCreationDate` is before `TrackingStartDate`, there is no record of the key being used for a successful cryptographic operation since the `TrackingStartDate`. However, the key may have been used before tracking began. To determine whether the key was used before the `TrackingStartDate`, examine your past AWS CloudTrail logs.

For multi-Region KMS keys, primary and replica keys track last usage independently. Each key in a multi-Region key set maintains its own usage information.

The `ReEncrypt` operation uses two keys: a source key for decryption and a destination key for encryption. Usage information is recorded for both keys independently, each with the AWS CloudTrail event ID from the respective key owner's account.

**Note**  
Do not use `GetKeyLastUsage` as the sole indicator when scheduling a key for deletion. Instead, first [disable the key](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html) and monitor AWS CloudTrail for `DisabledException` entries, as there could be infrequent workflows that are dependent on the key. By looking for this exception, you can identify potential dependencies and workload failures before they occur.

 **Cross-account use**: No. You cannot perform this operation on a KMS key in a different AWS account.

 **Required permissions**: [kms:GetKeyLastUsage](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) (key policy)

 **Related operations:** 
+  [DescribeKey](API_DescribeKey.md) 
+  [DisableKey](API_DisableKey.md) 
+  [ScheduleKeyDeletion](API_ScheduleKeyDeletion.md) 

 **Eventual consistency**: The AWS KMS API follows an eventual consistency model. For more information, see [AWS KMS eventual consistency](https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency).

## Request Syntax
<a name="API_GetKeyLastUsage_RequestSyntax"></a>

```
{
   "KeyId": "string"
}
```

## Request Parameters
<a name="API_GetKeyLastUsage_RequestParameters"></a>

For information about the parameters that are common to all actions, see [Common Parameters](CommonParameters.md).

The request accepts the following data in JSON format.

**Note**  
In the following list, the required parameters are described first.

 ** [KeyId](#API_GetKeyLastUsage_RequestSyntax) **   <a name="KMS-GetKeyLastUsage-request-KeyId"></a>
Identifies the KMS key to get usage information for. To specify a KMS key, use its key ID or key ARN. Alias names are not supported.  
Specify the key ID or key ARN of the KMS key.  
For example:  
+ Key ID: `1234abcd-12ab-34cd-56ef-1234567890ab` 
+ Key ARN: `arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab` 
To get the key ID and key ARN for a KMS key, use [ListKeys](API_ListKeys.md) or [DescribeKey](API_DescribeKey.md).  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 2048.  
Required: Yes

## Response Syntax
<a name="API_GetKeyLastUsage_ResponseSyntax"></a>

```
{
   "KeyCreationDate": number,
   "KeyId": "string",
   "KeyLastUsage": { 
      "CloudTrailEventId": "string",
      "KmsRequestId": "string",
      "Operation": "string",
      "Timestamp": number
   },
   "TrackingStartDate": number
}
```

## Response Elements
<a name="API_GetKeyLastUsage_ResponseElements"></a>

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

 ** [KeyCreationDate](#API_GetKeyLastUsage_ResponseSyntax) **   <a name="KMS-GetKeyLastUsage-response-KeyCreationDate"></a>
The date and time when the KMS key was created.  
Type: Timestamp

 ** [KeyId](#API_GetKeyLastUsage_ResponseSyntax) **   <a name="KMS-GetKeyLastUsage-response-KeyId"></a>
The globally unique identifier for the KMS key.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 2048.

 ** [KeyLastUsage](#API_GetKeyLastUsage_ResponseSyntax) **   <a name="KMS-GetKeyLastUsage-response-KeyLastUsage"></a>
Contains usage information about the last time the KMS key was used for a successful cryptographic operation. If the key has not been used since tracking began, this response element is empty.  
Type: [KeyLastUsageData](API_KeyLastUsageData.md) object

 ** [TrackingStartDate](#API_GetKeyLastUsage_ResponseSyntax) **   <a name="KMS-GetKeyLastUsage-response-TrackingStartDate"></a>
The date from which AWS KMS began recording cryptographic activity for this key, or the date the KMS key was created, whichever is later.  
Type: Timestamp

## Errors
<a name="API_GetKeyLastUsage_Errors"></a>

For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md).

 ** DependencyTimeoutException **   
The system timed out while trying to fulfill the request. You can retry the request.  
HTTP Status Code: 500

 ** InvalidArnException **   
The request was rejected because a specified ARN, or an ARN in a key policy, is not valid.  
HTTP Status Code: 400

 ** KMSInternalException **   
The request was rejected because an internal exception occurred. The request can be retried.  
HTTP Status Code: 500

 ** NotFoundException **   
The request was rejected because the specified entity or resource could not be found.  
HTTP Status Code: 400

## See Also
<a name="API_GetKeyLastUsage_SeeAlso"></a>

For more information about using this API in one of the language-specific AWS SDKs, see the following:
+  [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/kms-2014-11-01/GetKeyLastUsage) 
+  [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/kms-2014-11-01/GetKeyLastUsage)