PutDashboardCommand

Suggest an Edit

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.

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.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { CloudWatchClient, PutDashboardCommand } from "@aws-sdk/client-cloudwatch"; // ES Modules import
// const { CloudWatchClient, PutDashboardCommand } = require("@aws-sdk/client-cloudwatch"); // CommonJS import
const client = new CloudWatchClient(config);
const input = { // PutDashboardInput
  DashboardName: "STRING_VALUE", // required
  DashboardBody: "STRING_VALUE", // required
};
const command = new PutDashboardCommand(input);
const response = await client.send(command);
// { // PutDashboardOutput
//   DashboardValidationMessages: [ // DashboardValidationMessages
//     { // DashboardValidationMessage
//       DataPath: "STRING_VALUE",
//       Message: "STRING_VALUE",
//     },
//   ],
// };

PutDashboardCommand Input

See PutDashboardCommandInput for more details

Parameter
Type
Description
DashboardBody
Required
string | undefined

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 .

DashboardName
Required
string | undefined

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.

PutDashboardCommand Output

See PutDashboardCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
DashboardValidationMessages
DashboardValidationMessage[] | undefined

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 might not render.

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

Throws

Name
Fault
Details
DashboardInvalidInputError
client

Some part of the dashboard data is invalid.

InternalServiceFault
server

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

CloudWatchServiceException
Base exception class for all service exceptions from CloudWatch service.