This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).

# AWS::CloudTrail::Dashboard
<a name="aws-resource-cloudtrail-dashboard"></a>

**Important**  
CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see [CloudTrail Lake availability change](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-service-availability-change.html).

 Creates a custom dashboard or the Highlights dashboard. 
+ **Custom dashboards** - Custom dashboards allow you to query events in any event data store type. You can add up to 10 widgets to a custom dashboard. You can manually refresh a custom dashboard, or you can set a refresh schedule.
+ **Highlights dashboard** - You can create the Highlights dashboard to see a summary of key user activities and API usage across all your event data stores. CloudTrail Lake manages the Highlights dashboard and refreshes the dashboard every 6 hours. To create the Highlights dashboard, you must set and enable a refresh schedule.

 CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the `StartQuery` operation on your behalf. To provide permissions, run the `PutResourcePolicy` operation to attach a resource-based policy to each event data store. For more information, see [Example: Allow CloudTrail to run queries to populate a dashboard](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/security_iam_resource-based-policy-examples.html#security_iam_resource-based-policy-examples-eds-dashboard) in the *AWS CloudTrail User Guide*. 

 To set a refresh schedule, CloudTrail must be granted permissions to run the `StartDashboardRefresh` operation to refresh the dashboard on your behalf. To provide permissions, run the `PutResourcePolicy` operation to attach a resource-based policy to the dashboard. For more information, see [ Resource-based policy example for a dashboard](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/security_iam_resource-based-policy-examples.html#security_iam_resource-based-policy-examples-dashboards) in the *AWS CloudTrail User Guide*. 

For more information about dashboards, see [CloudTrail Lake dashboards](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/lake-dashboard.html) in the *AWS CloudTrail User Guide*.

## Syntax
<a name="aws-resource-cloudtrail-dashboard-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-resource-cloudtrail-dashboard-syntax.json"></a>

```
{
  "Type" : "AWS::CloudTrail::Dashboard",
  "Properties" : {
      "[Name](#cfn-cloudtrail-dashboard-name)" : String,
      "[RefreshSchedule](#cfn-cloudtrail-dashboard-refreshschedule)" : RefreshSchedule,
      "[Tags](#cfn-cloudtrail-dashboard-tags)" : [ Tag, ... ],
      "[TerminationProtectionEnabled](#cfn-cloudtrail-dashboard-terminationprotectionenabled)" : Boolean,
      "[Widgets](#cfn-cloudtrail-dashboard-widgets)" : [ Widget, ... ]
    }
}
```

### YAML
<a name="aws-resource-cloudtrail-dashboard-syntax.yaml"></a>

```
Type: AWS::CloudTrail::Dashboard
Properties:
  [Name](#cfn-cloudtrail-dashboard-name): String
  [RefreshSchedule](#cfn-cloudtrail-dashboard-refreshschedule): 
    RefreshSchedule
  [Tags](#cfn-cloudtrail-dashboard-tags): 
    - Tag
  [TerminationProtectionEnabled](#cfn-cloudtrail-dashboard-terminationprotectionenabled): Boolean
  [Widgets](#cfn-cloudtrail-dashboard-widgets): 
    - Widget
```

## Properties
<a name="aws-resource-cloudtrail-dashboard-properties"></a>

`Name`  <a name="cfn-cloudtrail-dashboard-name"></a>
 The name of the dashboard. The name must be unique to your account.   
To create the Highlights dashboard, the name must be `AWSCloudTrail-Highlights`.  
*Required*: No  
*Type*: String  
*Pattern*: `^[a-zA-Z0-9_\-]+$`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`RefreshSchedule`  <a name="cfn-cloudtrail-dashboard-refreshschedule"></a>
 The schedule for a dashboard refresh.   
*Required*: No  
*Type*: [RefreshSchedule](aws-properties-cloudtrail-dashboard-refreshschedule.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Tags`  <a name="cfn-cloudtrail-dashboard-tags"></a>
A list of tags.  
*Required*: No  
*Type*: Array of [Tag](aws-properties-cloudtrail-dashboard-tag.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`TerminationProtectionEnabled`  <a name="cfn-cloudtrail-dashboard-terminationprotectionenabled"></a>
 Specifies whether termination protection is enabled for the dashboard. If termination protection is enabled, you cannot delete the dashboard until termination protection is disabled.   
*Required*: No  
*Type*: Boolean  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Widgets`  <a name="cfn-cloudtrail-dashboard-widgets"></a>
 An array of widgets for a custom dashboard. A custom dashboard can have a maximum of ten widgets.   
You do not need to specify widgets for the Highlights dashboard.  
*Required*: No  
*Type*: Array of [Widget](aws-properties-cloudtrail-dashboard-widget.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

## Return values
<a name="aws-resource-cloudtrail-dashboard-return-values"></a>

### Ref
<a name="aws-resource-cloudtrail-dashboard-return-values-ref"></a>

### Fn::GetAtt
<a name="aws-resource-cloudtrail-dashboard-return-values-fn--getatt"></a>

#### 
<a name="aws-resource-cloudtrail-dashboard-return-values-fn--getatt-fn--getatt"></a>

`CreatedTimestamp`  <a name="CreatedTimestamp-fn::getatt"></a>
 The timestamp that shows when the dashboard was created. 

`DashboardArn`  <a name="DashboardArn-fn::getatt"></a>
 The ARN for the dashboard. 

`Status`  <a name="Status-fn::getatt"></a>
 The status of the dashboard. 

`Type`  <a name="Type-fn::getatt"></a>
 The type of dashboard. 

`UpdatedTimestamp`  <a name="UpdatedTimestamp-fn::getatt"></a>
 The timestamp that shows when the dashboard was updated. 

## Examples
<a name="aws-resource-cloudtrail-dashboard--examples"></a>

### Example: Create a custom dashboard
<a name="aws-resource-cloudtrail-dashboard--examples--Example:_Create_a_custom_dashboard"></a>

The following example creates a custom dashboard named `AccountActivityDashboard` with four widgets. In this example, a refresh schedule has been set for every 6 hours and termination protection is enabled to prevent the dashboard from being accidentally deleted.

#### JSON
<a name="aws-resource-cloudtrail-dashboard--examples--Example:_Create_a_custom_dashboard--json"></a>

```
{
    "Resources": {
        "Dashboard": {
            "Type": "AWS::CloudTrail::Dashboard",
            "Properties": {
                "Name": "AccountActivityDashboard",
                "RefreshSchedule": {
                    "Frequency": {
                        "Unit": "HOURS",
                        "Value": 6
                    },
                    "Status": "ENABLED",
                    "TimeOfDay": "00:00"
                },
                "Tags": [{
                        "Key": "k1",
                        "Value": "v1"
                    },
                    {
                        "Key": "k2",
                        "Value": "v2"
                    }
                ],
                "TerminationProtectionEnabled": true,
                "Widgets": [{
                        "ViewProperties": {
                            "Height": "2",
                            "Width": "4",
                            "Title": "TopErrors",
                            "View": "Table"
                        },
                        "QueryStatement": "SELECT errorCode, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' AND (errorCode is not null) GROUP BY errorCode ORDER BY eventCount DESC LIMIT 100",
                        "QueryParameters": ["$StartTime$", "$EndTime$"]
                    },
                    {
                        "ViewProperties": {
                            "Height": "2",
                            "Width": "4",
                            "Title": "MostActiveRegions",
                            "View": "PieChart",
                            "LabelColumn": "awsRegion",
                            "ValueColumn": "eventCount",
                            "FilterColumn": "awsRegion"
                        },
                        "QueryStatement": "SELECT awsRegion, COUNT(*) AS eventCount FROM eds where eventTime > '?' and eventTime < '?' GROUP BY awsRegion ORDER BY eventCount LIMIT 100",
                        "QueryParameters": ["$StartTime$", "$EndTime$"]
                    },
                    {
                        "ViewProperties": {
                            "Height": "2",
                            "Width": "4",
                            "Title": "AccountActivity",
                            "View": "LineChart",
                            "YAxisColumn": "eventCount",
                            "XAxisColumn": "eventDate",
                            "FilterColumn": "readOnly"
                        },
                        "QueryStatement": "SELECT DATE_TRUNC('?', eventTime) AS eventDate, IF(readOnly, 'read', 'write') AS readOnly, COUNT(*) as eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY DATE_TRUNC('?', eventTime), readOnly ORDER BY DATE_TRUNC('?', eventTime), readOnly",
                        "QueryParameters": ["$Period$", "$StartTime$", "$EndTime$", "$Period$", "$Period$"]
                    },
                    {
                        "ViewProperties": {
                            "Height": "2",
                            "Width": "4",
                            "Title": "TopServices",
                            "View": "BarChart",
                            "LabelColumn": "service",
                            "ValueColumn": "eventCount",
                            "FilterColumn": "service",
                            "Orientation": "Horizontal"
                        },
                        "QueryStatement": "SELECT REPLACE(eventSource, '.amazonaws.com') AS service, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY eventSource ORDER BY eventCount DESC LIMIT 100",
                        "QueryParameters": ["$StartTime$", "$EndTime$"]
                    }
                ]
            }
        }
    }
}
```

#### YAML
<a name="aws-resource-cloudtrail-dashboard--examples--Example:_Create_a_custom_dashboard--yaml"></a>

```
Resources:
  Dashboard:
    Type: 'AWS::CloudTrail::Dashboard'
    Properties:
      Name: "AccountActivityDashboard"
      TerminationProtectionEnabled: true
      RefreshSchedule:
        Frequency:
          Unit: "HOURS"
          Value: 6
        Status: "ENABLED"
        TimeOfDay: "00:00"
      Tags:
        - Key: "k1"
          Value: "v1"
        - Key: "k2"
          Value: "v2"
      Widgets:
        - QueryStatement: "SELECT errorCode, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' AND (errorCode is not null) GROUP BY errorCode ORDER BY eventCount DESC LIMIT 100"
          QueryParameters:
            - "$StartTime$"
            - "$EndTime$"
          ViewProperties:
            Height: "2"
            Width: "4"
            Title: "TopErrors"
            View: "Table"
        - QueryStatement: "SELECT awsRegion, COUNT(*) AS eventCount FROM eds where eventTime > '?' and eventTime < '?' GROUP BY awsRegion ORDER BY eventCount LIMIT 100"
          QueryParameters:
            - "$StartTime$"
            - "$EndTime$"
          ViewProperties:
            Height: "2"
            Width: "4"
            Title: "MostActiveRegions"
            View: "PieChart"
            LabelColumn: "awsRegion"
            ValueColumn: "eventCount"
            FilterColumn: "awsRegion"
        - QueryStatement: "SELECT DATE_TRUNC('?', eventTime) AS eventDate, IF(readOnly, 'read', 'write') AS readOnly, COUNT(*) as eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY DATE_TRUNC('?', eventTime), readOnly ORDER BY DATE_TRUNC('?', eventTime), readOnly"
          QueryParameters:
            - "$Period$"
            - "$StartTime$"
            - "$EndTime$"
            - "$Period$"
            - "$Period$"
          ViewProperties:
            Height: "2"
            Width: "4"
            Title: "AccountActivity"
            View: "LineChart"
            YAxisColumn: "eventCount"
            XAxisColumn: "eventDate"
            FilterColumn: "readOnly"
        - QueryStatement: "SELECT REPLACE(eventSource, '.amazonaws.com') AS service, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY eventSource ORDER BY eventCount DESC LIMIT 100"
          QueryParameters:
            - "$StartTime$"
            - "$EndTime$"
          ViewProperties:
            Height: "2"
            Width: "4"
            Title: "TopServices"
            View: "BarChart"
            LabelColumn: "service"
            ValueColumn: "eventCount"
            FilterColumn: "service"
            Orientation: "Horizontal"
```

# AWS::CloudTrail::Dashboard Frequency
<a name="aws-properties-cloudtrail-dashboard-frequency"></a>

 Specifies the frequency for a dashboard refresh schedule. 

 For a custom dashboard, you can schedule a refresh for every 1, 6, 12, or 24 hours, or every day. 

## Syntax
<a name="aws-properties-cloudtrail-dashboard-frequency-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-cloudtrail-dashboard-frequency-syntax.json"></a>

```
{
  "[Unit](#cfn-cloudtrail-dashboard-frequency-unit)" : String,
  "[Value](#cfn-cloudtrail-dashboard-frequency-value)" : Integer
}
```

### YAML
<a name="aws-properties-cloudtrail-dashboard-frequency-syntax.yaml"></a>

```
  [Unit](#cfn-cloudtrail-dashboard-frequency-unit): String
  [Value](#cfn-cloudtrail-dashboard-frequency-value): Integer
```

## Properties
<a name="aws-properties-cloudtrail-dashboard-frequency-properties"></a>

`Unit`  <a name="cfn-cloudtrail-dashboard-frequency-unit"></a>
 The unit to use for the refresh.   
For custom dashboards, the unit can be `HOURS` or `DAYS`.  
For the Highlights dashboard, the `Unit` must be `HOURS`.  
*Required*: Yes  
*Type*: String  
*Allowed values*: `HOURS | DAYS`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Value`  <a name="cfn-cloudtrail-dashboard-frequency-value"></a>
 The value for the refresh schedule.   
 For custom dashboards, the following values are valid when the unit is `HOURS`: `1`, `6`, `12`, `24`  
For custom dashboards, the only valid value when the unit is `DAYS` is `1`.  
For the Highlights dashboard, the `Value` must be `6`.  
*Required*: Yes  
*Type*: Integer  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

# AWS::CloudTrail::Dashboard RefreshSchedule
<a name="aws-properties-cloudtrail-dashboard-refreshschedule"></a>

 The schedule for a dashboard refresh. 

## Syntax
<a name="aws-properties-cloudtrail-dashboard-refreshschedule-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-cloudtrail-dashboard-refreshschedule-syntax.json"></a>

```
{
  "[Frequency](#cfn-cloudtrail-dashboard-refreshschedule-frequency)" : Frequency,
  "[Status](#cfn-cloudtrail-dashboard-refreshschedule-status)" : String,
  "[TimeOfDay](#cfn-cloudtrail-dashboard-refreshschedule-timeofday)" : String
}
```

### YAML
<a name="aws-properties-cloudtrail-dashboard-refreshschedule-syntax.yaml"></a>

```
  [Frequency](#cfn-cloudtrail-dashboard-refreshschedule-frequency): 
    Frequency
  [Status](#cfn-cloudtrail-dashboard-refreshschedule-status): String
  [TimeOfDay](#cfn-cloudtrail-dashboard-refreshschedule-timeofday): String
```

## Properties
<a name="aws-properties-cloudtrail-dashboard-refreshschedule-properties"></a>

`Frequency`  <a name="cfn-cloudtrail-dashboard-refreshschedule-frequency"></a>
 The frequency at which you want the dashboard refreshed.   
*Required*: No  
*Type*: [Frequency](aws-properties-cloudtrail-dashboard-frequency.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Status`  <a name="cfn-cloudtrail-dashboard-refreshschedule-status"></a>
 Specifies whether the refresh schedule is enabled. Set the value to `ENABLED` to enable the refresh schedule, or to `DISABLED` to turn off the refresh schedule.   
*Required*: No  
*Type*: String  
*Allowed values*: `ENABLED | DISABLED`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`TimeOfDay`  <a name="cfn-cloudtrail-dashboard-refreshschedule-timeofday"></a>
 The time of day in UTC to run the schedule; for hourly only refer to minutes; default is 00:00.   
*Required*: No  
*Type*: String  
*Pattern*: `^[0-9]{2}:[0-9]{2}`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

# AWS::CloudTrail::Dashboard Tag
<a name="aws-properties-cloudtrail-dashboard-tag"></a>

A custom key-value pair associated with a dashboard resource.

## Syntax
<a name="aws-properties-cloudtrail-dashboard-tag-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-cloudtrail-dashboard-tag-syntax.json"></a>

```
{
  "[Key](#cfn-cloudtrail-dashboard-tag-key)" : String,
  "[Value](#cfn-cloudtrail-dashboard-tag-value)" : String
}
```

### YAML
<a name="aws-properties-cloudtrail-dashboard-tag-syntax.yaml"></a>

```
  [Key](#cfn-cloudtrail-dashboard-tag-key): String
  [Value](#cfn-cloudtrail-dashboard-tag-value): String
```

## Properties
<a name="aws-properties-cloudtrail-dashboard-tag-properties"></a>

`Key`  <a name="cfn-cloudtrail-dashboard-tag-key"></a>
The key in a key-value pair. The key must be must be no longer than 128 Unicode characters. The key must be unique for the resource to which it applies.  
*Required*: Yes  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `128`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Value`  <a name="cfn-cloudtrail-dashboard-tag-value"></a>
The value in a key-value pair of a tag. The value must be no longer than 256 Unicode characters.  
*Required*: Yes  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `256`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

# AWS::CloudTrail::Dashboard Widget
<a name="aws-properties-cloudtrail-dashboard-widget"></a>

 Contains information about a widget on a CloudTrail Lake dashboard. 

## Syntax
<a name="aws-properties-cloudtrail-dashboard-widget-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-properties-cloudtrail-dashboard-widget-syntax.json"></a>

```
{
  "[QueryParameters](#cfn-cloudtrail-dashboard-widget-queryparameters)" : [ String, ... ],
  "[QueryStatement](#cfn-cloudtrail-dashboard-widget-querystatement)" : String,
  "[ViewProperties](#cfn-cloudtrail-dashboard-widget-viewproperties)" : {Key: Value, ...}
}
```

### YAML
<a name="aws-properties-cloudtrail-dashboard-widget-syntax.yaml"></a>

```
  [QueryParameters](#cfn-cloudtrail-dashboard-widget-queryparameters): 
    - String
  [QueryStatement](#cfn-cloudtrail-dashboard-widget-querystatement): String
  [ViewProperties](#cfn-cloudtrail-dashboard-widget-viewproperties): 
    Key: Value
```

## Properties
<a name="aws-properties-cloudtrail-dashboard-widget-properties"></a>

`QueryParameters`  <a name="cfn-cloudtrail-dashboard-widget-queryparameters"></a>
 The optional query parameters. The following query parameters are valid: `$StartTime$`, `$EndTime$`, and `$Period$`.   
*Required*: No  
*Type*: Array of String  
*Minimum*: `1`  
*Maximum*: `10`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`QueryStatement`  <a name="cfn-cloudtrail-dashboard-widget-querystatement"></a>
 The query statement for the widget. For custom dashboard widgets, you can query across multiple event data stores as long as all event data stores exist in your account.   
When a query uses `?` with `eventTime`, `?` must be surrounded by single quotes as follows: `'?'`.
*Required*: Yes  
*Type*: String  
*Pattern*: `(?s).*`  
*Minimum*: `1`  
*Maximum*: `10000`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`ViewProperties`  <a name="cfn-cloudtrail-dashboard-widget-viewproperties"></a>
 The view properties for the widget. For more information about view properties, see [ View properties for widgets ](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/lake-widget-properties.html) in the *AWS CloudTrail User Guide*.   
*Required*: No  
*Type*: Object of String  
*Pattern*: `^[a-zA-Z0-9._-]{3,128}$`  
*Minimum*: `1`  
*Maximum*: `128`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)