Amazon CloudWatch
API Reference (API Version 2010-08-01)


Creates a dashboard if it does not already exist, or updates an existing dashboard. If you update a dashboard, the entire contents are replaced with what you specify here.

You can have up to 500 dashboards per account. All dashboards in your account are global, not region-specific.

A simple way to create a dashboard using PutDashboard is to copy an existing dashboard. To copy an existing dashboard using the console, you can load the dashboard and then use the View/edit source command in the Actions menu to display the JSON block for that dashboard. Another way to copy a dashboard is to use GetDashboard, and then use the data returned within DashboardBody as the template for the new dashboard when you call PutDashboard.

When you create a dashboard with PutDashboard, a good practice is to add a text widget at the top of the dashboard with a message that the dashboard was created by script and should not be changed in the console. This message could also point console users to the location of the DashboardBody script or the CloudFormation template used to create the dashboard.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.


The detailed information about the dashboard in JSON format, including the widgets to include and their location on the dashboard. This parameter is required.

For more information about the syntax, see Dashboard Body Structure and Syntax.

Type: String

Required: Yes


The name of the dashboard. If a dashboard with this name already exists, this call modifies that dashboard, replacing its current contents. Otherwise, a new dashboard is created. The maximum length is 255, and valid characters are A-Z, a-z, 0-9, "-", and "_". This parameter is required.

Type: String

Required: Yes

Response Elements

The following element is returned by the service.


If the input for PutDashboard was correct and the dashboard was successfully created or modified, this result is empty.

If this result includes only warning messages, then the input was valid enough for the dashboard to be created or modified, but some elements of the dashboard may not render.

If this result includes error messages, the input was not valid and the operation failed.

Type: Array of DashboardValidationMessage objects


For information about the errors that are common to all actions, see Common Errors.


Request processing has failed due to some unknown error, exception, or failure.

HTTP Status Code: 500


Some part of the dashboard data is invalid.

HTTP Status Code: 400



The following example creates a dashboard with just one text widget.

{ "DashBoardName":"Dashboard with only one text widget" "DashBoardBody": { "widgets":[ { "type":"text", "x":0, "y":7, "width":3, "height":3, "properties":{ "markdown":"Hello world" } } ] } }


The following example modifies an existing dashboard to include one metric widget and one text widget.

{ "DashBoardName":"Two-Widget Dashboard" "DashBoardBody": { "widgets":[ { "type":"metric", "x":0, "y":0, "width":12, "height":6, "properties":{ "metrics":[ [ "AWS/EC2", "CPUUtilization", "InstanceId", "i-012345" ] ], "period":300, "stat":"Average", "region":"us-east-1", "title":"EC2 Instance CPU" } }, { "type":"text", "x":0, "y":7, "width":3, "height":3, "properties":{ "markdown":"Hello world" } } ] } }


The following example creates a dashboard with two separate metric widgets, side by side.

{ "DashBoardName":"Two-metric-widget Dashboard" "DashBoardBody": { "widgets":[ { "type":"metric", "x":0, "y":0, "width":12, "height":6, "properties":{ "metrics":[ [ "AWS/EC2", "CPUUtilization", "InstanceId", "i-012345" ] ], "period":300, "stat":"Average", "region":"us-east-1", "title":"EC2 Instance CPU" } }, { "type":"metric", "x":12, "y":0, "width":12, "height":6, "properties":{ "metrics":[ [ "AWS/S3", "BucketSizeBytes", "BucketName", "MyBucketName" ] ], "period":86400, "stat":"Maximum", "region":"us-east-1", "title":"MyBucketName bytes" } } ] } }


The following example creates a dashboard with one widget at the top that shows the DiskReadBytes metric for three EC2 instances on one graph, and a separate widget below that, with an alarm.

{ "DashBoardName":"Dashboard with a three-metric graph and an alarm" "DashBoardBody": { "widgets":[ { "type":"metric", "x":0, "y":0, "width":12, "height":6, "properties":{ "metrics":[ [ "AWS/EC2","DiskReadBytes","InstanceId","i-xyz" ], [ ".",".",".","i-abc" ], [ ".",".",".","i-123" ] ], "period":300, "stat":"Average", "region":"us-east-1", "title":"EC2 Instance CPU" } }, { "type":"metric", "x":0, "y":7, "width":12, "height":12, "properties":{ "annotations":{ "alarms":[ "arn:aws:cloudwatch:us-east-1:123456789012:alarm:myalarm" ] }, "period":60, "title":"MyAlarm" } } ] } }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: