Amazon CloudWatch

Publish and read CloudWatch metrics, manage alarms and dashboards, and write, search and query CloudWatch Logs.

Actions

Action	What it does
Create log group	Create a CloudWatch Logs log group.
Create log stream	Create a log stream in a log group, to write events to.
Create or update alarm	Create an alarm that watches one metric against a threshold.
Delete alarms	Delete up to 100 alarms by name.
Delete dashboards	Delete one or more dashboards.
Delete log group	Delete a log group with all its streams and events.
Get alarm history	Read alarms' state changes, configuration updates and actions (kept for 30 days), newest first.
Get dashboard	Read a dashboard's body (its widgets) and ARN.
Get metric statistics	Read a metric's average, sum, minimum, maximum, sample count or percentiles over a time window, one datapoint per period, oldest first.
Get query results	Read a Logs Insights query's rows.
List alarms	List alarms with their current state, by name, name prefix, state or type.
List dashboards	List the account's dashboards, optionally by name prefix.
List log groups	List log groups in the region, by name prefix or by a text the name contains.
List metrics	List the metrics in the connected region, optionally by namespace, name or dimension.
Publish metric data point	Publish one value to a custom metric, creating the metric the first time.
Save dashboard	Create a dashboard, or replace an existing dashboard's whole body.
Search log events	Find log events in a log group that match a filter pattern, oldest first.
Set alarm state (test)	Force an alarm into a state to test its actions - they run as if it happened.
Start Logs Insights query	Start a CloudWatch Logs Insights query over one or more log groups.
Write log events	Write one or more log lines to a log stream.

Create log group

Create a CloudWatch Logs log group. Events are kept forever unless a retention period is set in the console.

Inputs

Log group namelog_group_nametextRequired: Up to 512 letters, digits and '_', '-', '/', '.', '#', for example /myapp/production. It must not start with 'aws/'.
Log classlog_group_classtext: Standard, or Infrequent Access (cheaper ingestion, fewer features). Cannot be changed later. Default Standard.One of: STANDARD, INFREQUENT_ACCESS (Infrequent Access (cheaper)).
Tagstagsobject: Tags as key: value pairs.

Outputs

resultobject

Example output

{
  "result": {
    "created": true,
    "log_group_class": "STANDARD",
    "log_group_name": "/myapp/production",
    "tags": {}
  }
}

Create log stream

Create a log stream in a log group, to write events to.

Inputs

Log grouplog_group_nametextRequired: The log group's name, for example /aws/lambda/my-function, or its ARN. Use List log groups to find one.
Log stream namelog_stream_nametextRequired: The new stream's name, up to 512 characters. No ':' or '*'.

Outputs

resultobject

Example output

{
  "result": {
    "created": true,
    "log_group_name": "/myapp/production",
    "log_stream_name": "web-1"
  }
}

Create or update alarm

Create an alarm that watches one metric against a threshold. If an alarm with this name exists it is replaced entirely (tags are kept). A new alarm starts in INSUFFICIENT_DATA.

Inputs

Alarm namealarm_nametextRequired: The alarm's exact name (case-sensitive).
NamespacenamespacetextRequired: The metric's namespace, for example AWS/EC2 or your own 'MyApp'.
Metric namemetric_nametextRequired: The metric's name, for example CPUUtilization.
Dimensionsdimensionsobject: The metric's dimensions as name: value pairs, exactly as published (for example InstanceId: i-0123456789abcdef0).
Conditioncomparison_operatortextRequired: How the metric is compared with the threshold.One of: GreaterThanOrEqualToThreshold (>= threshold), GreaterThanThreshold (> threshold), LessThanThreshold (< threshold), LessThanOrEqualToThreshold (<= threshold).
ThresholdthresholdnumberRequired: The value to compare against.
Statisticstatistictext: How each period's values are combined. Default Average.One of: SampleCount, Average, Sum, Minimum, Maximum.
Percentileextended_statistictext: A percentile instead of a statistic, for example p99. Leave Statistic empty when you use this.
Period (seconds)periodnumber: Seconds per evaluated period: 60 or a multiple of it (10, 20 and 30 make a charged high-resolution alarm). Default 300.From 10 to 86400.
Evaluation periodsevaluation_periodsnumber: How many recent periods are evaluated. Default 1.From 1 to 10080.
Datapoints to alarmdatapoints_to_alarmnumber: How many of those periods must breach to alarm (an 'M out of N' alarm). Default all of them.From 1 to 10080.
Missing datatreat_missing_datatext: How periods with no data count.One of: breaching (Treat as breaching), notBreaching (Treat as not breaching), ignore (Ignore (keep the current state)), missing (Missing (the default)).
Unitunittext: The unit of the values. Leave empty for none.One of: Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, and 17 more.
Descriptionalarm_descriptiontext: A description, up to 1024 characters.
Alarm actionsalarm_actionslist: Up to 5 ARNs to notify on entering ALARM, for example an SNS topic ARN.
OK actionsok_actionslist: Up to 5 ARNs to notify on returning to OK.
Insufficient data actionsinsufficient_data_actionslist: Up to 5 ARNs to notify on INSUFFICIENT_DATA.
Actions enabledactions_enabledtrue/false: Whether the actions above run. Default on.Default: true.
Tagstagsobject: Tags as key: value pairs. Only applied when the alarm is created, not on an update.

Outputs

resultobject

Example output

{
  "result": {
    "alarm_name": "high-cpu",
    "comparison_operator": "GreaterThanThreshold",
    "evaluation_periods": 2,
    "metric_name": "CPUUtilization",
    "namespace": "AWS/EC2",
    "period": 300,
    "saved": true,
    "statistic": "Average",
    "threshold": 80.0
  }
}

Delete alarms

Delete up to 100 alarms by name. There is no undo. Names that do not exist are skipped while the rest are deleted.

Inputs

Alarm namesalarm_nameslistRequired: The exact names of the alarms to delete.

Outputs

resultobject

Example output

{
  "result": {
    "alarm_names": [
      "high-cpu"
    ],
    "count": 1,
    "deleted": true
  }
}

Delete dashboards

Delete one or more dashboards. There is no undo.

Inputs

Dashboardsdashboard_nameslistRequired: The dashboards to delete (up to 100).

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "dashboard_names": [
      "ops"
    ],
    "deleted": true
  }
}

Delete log group

Delete a log group with all its streams and events. There is no undo.

Inputs

Log grouplog_group_nametextRequired: The log group's name, for example /aws/lambda/my-function, or its ARN. Use List log groups to find one.

Outputs

resultobject

Example output

{
  "result": {
    "deleted": true,
    "log_group_name": "/myapp/production"
  }
}

Get alarm history

Read alarms' state changes, configuration updates and actions (kept for 30 days), newest first.

Inputs

Alarm namealarm_nametext: Only this alarm. Leave empty for every alarm.
Entry typehistory_item_typetext: Only this kind of entry.One of: ConfigurationUpdate (Configuration updates), StateUpdate (State changes), Action (Actions taken).
Alarm typesalarm_typeslist: Only these kinds of alarm.One or more of: MetricAlarm (Metric alarms), CompositeAlarm (Composite alarms), LogAlarm (Log alarms).
Fromstart_timedate and time: From this time.
Toend_timedate and time: Up to this time. Leave empty for now.
Orderscan_bytext: Order of the entries. Default newest first.One of: TimestampDescending (Newest first), TimestampAscending (Oldest first).
Max recordsmax_recordsnumber: How many per page, 1-100. Default 100.From 1 to 100.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "has_more": false,
    "items": [
      {
        "alarm_name": "high-cpu",
        "alarm_type": "MetricAlarm",
        "history_data": {
          "version": "1.0"
        },
        "history_item_type": "StateUpdate",
        "history_summary": "Alarm updated from OK to ALARM",
        "timestamp": "2026-09-29T09:05:00Z"
      }
    ],
    "next_token": null
  }
}

Get dashboard

Read a dashboard's body (its widgets) and ARN.

Inputs

Dashboarddashboard_nametextRequired: Pick a dashboard, or type its name.

Outputs

resultobject

Example output

{
  "result": {
    "dashboard_arn": "arn:aws:cloudwatch::123456789012:dashboard/ops",
    "dashboard_body": {
      "widgets": []
    },
    "dashboard_body_text": "{\"widgets\":[]}",
    "dashboard_name": "ops",
    "widget_count": 0
  }
}

Get metric statistics

Read a metric's average, sum, minimum, maximum, sample count or percentiles over a time window, one datapoint per period, oldest first. Defaults to the last 3 hours in 5-minute periods.

Inputs

NamespacenamespacetextRequired: The metric's namespace, for example AWS/EC2 or your own 'MyApp'.
Metric namemetric_nametextRequired: The metric's name, for example CPUUtilization.
Dimensionsdimensionsobject: The metric's dimensions as name: value pairs, exactly as published (for example InstanceId: i-0123456789abcdef0).
Fromstart_timedate and time: From this time. Leave empty for 3 hours ago.
Toend_timedate and time: Up to this time. Leave empty for now.
Period (seconds)periodnumber: Seconds per datapoint: a multiple of 60 (or 1, 5, 10, 20, 30 for high-resolution metrics). Default 300.From 1 to 86400.
Statisticsstatisticslist: Which statistics to read. Default Average.One or more of: SampleCount, Average, Sum, Minimum, Maximum.
Percentilesextended_statisticslist: Percentiles instead of statistics, for example p99 or p95. Up to 10.
Unitunittext: The unit of the values. Leave empty for none.One of: Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, and 17 more.

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "datapoints": [
      {
        "average": 12.4,
        "extended_statistics": {},
        "maximum": null,
        "minimum": null,
        "sample_count": 5.0,
        "sum": null,
        "timestamp": "2026-09-29T09:00:00Z",
        "unit": "Percent"
      }
    ],
    "end_time": "2026-09-29T09:00:00Z",
    "label": "CPUUtilization",
    "latest": {
      "average": 12.4,
      "extended_statistics": {},
      "maximum": null,
      "minimum": null,
      "sample_count": 5.0,
      "sum": null,
      "timestamp": "2026-09-29T09:00:00Z",
      "unit": "Percent"
    },
    "metric_name": "CPUUtilization",
    "namespace": "AWS/EC2",
    "period": 300,
    "start_time": "2026-09-29T06:00:00Z"
  }
}

Get query results

Read a Logs Insights query's rows. Set a wait time to wait for a query that is still running; otherwise check 'complete'. Results are kept for 7 days.

Inputs

Query idquery_idtextRequired: The query_id from Start Logs Insights query.
Wait (seconds)wait_secondsnumber: Wait up to this long, 0-60, for the query to finish. Default 0 (return straight away).From 0 to 60.

Outputs

resultobject

Example output

{
  "result": {
    "complete": true,
    "count": 1,
    "query_id": "12ab3456-12ab-123a-789e-1234567890ab",
    "rows": [
      {
        "@message": "ERROR payment declined order=1042",
        "@ptr": "CmAKJgoiMTIzNDU2Nzg5MDEyOi9teWFwcC9wcm9kdWN0aW9u",
        "@timestamp": "2026-09-29 09:00:00.000"
      }
    ],
    "statistics": {
      "bytes_scanned": 14000.0,
      "log_groups_scanned": 1.0,
      "records_matched": 1.0,
      "records_scanned": 120.0
    },
    "status": "Complete"
  }
}

List alarms

List alarms with their current state, by name, name prefix, state or type.

Inputs

Alarm namesalarm_nameslist: Only these alarms (exact names, up to 100).
Name prefixalarm_name_prefixtext: Only alarms whose name starts with this. Not with Alarm names.
Statestate_valuetext: Only alarms in this state.One of: OK, ALARM, INSUFFICIENT_DATA.
Alarm typesalarm_typeslist: Which kinds of alarm. Default metric alarms only.One or more of: MetricAlarm (Metric alarms), CompositeAlarm (Composite alarms), LogAlarm (Log alarms).
Action prefixaction_prefixtext: Only alarms with an action ARN starting with this, for example an SNS topic ARN.
Max recordsmax_recordsnumber: How many per page, 1-100. Default 50.From 1 to 100.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.

Outputs

resultobject

Example output

{
  "result": {
    "alarm_names": [
      "high-cpu"
    ],
    "composite_alarms": [],
    "count": 1,
    "has_more": false,
    "in_alarm_count": 0,
    "log_alarms": [],
    "metric_alarms": [
      {
        "actions_enabled": true,
        "alarm_actions": [
          "arn:aws:sns:us-east-1:123456789012:alerts"
        ],
        "alarm_arn": "arn:aws:cloudwatch:us-east-1:123456789012:alarm:high-cpu",
        "alarm_description": "CPU above 80% for 10 minutes",
        "alarm_name": "high-cpu",
        "comparison_operator": "GreaterThanThreshold",
        "configuration_updated_at": "2026-09-29T08:00:00Z",
        "datapoints_to_alarm": null,
        "dimensions": {
          "InstanceId": "i-0123456789abcdef0"
        },
        "evaluation_periods": 2,
        "evaluation_state": null,
        "extended_statistic": null,
        "insufficient_data_actions": [],
        "metric_name": "CPUUtilization",
        "namespace": "AWS/EC2",
        "ok_actions": [],
        "period": 300,
        "state_reason": "Threshold Crossed: 2 datapoints were not greater than 80.0",
        "state_reason_data": {
          "statistic": "Average",
          "version": "1.0"
        },
        "state_transitioned_at": "2026-09-29T09:05:00Z",
        "state_updated_at": "2026-09-29T09:05:00Z",
        "state_value": "OK",
        "statistic": "Average",
        "threshold": 80.0,
        "treat_missing_data": "missing",
        "unit": null
      }
    ],
    "next_token": null
  }
}

List dashboards

List the account's dashboards, optionally by name prefix.

Inputs

Name prefixdashboard_name_prefixtext: Only dashboards whose name starts with this.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "dashboards": [
      {
        "dashboard_arn": "arn:aws:cloudwatch::123456789012:dashboard/ops",
        "dashboard_name": "ops",
        "last_modified": "2026-09-29T08:00:00Z",
        "size": 250
      }
    ],
    "has_more": false,
    "next_token": null
  }
}

List log groups

List log groups in the region, by name prefix or by a text the name contains. Up to 50 per page.

Inputs

Name prefixlog_group_name_prefixtext: Only groups whose name starts with this.
Name containslog_group_name_patterntext: Only groups whose name contains this (case-insensitive). Not with Name prefix. Returns only name, ARN and creation time.
Log classlog_group_classtext: Only groups of this class.One of: STANDARD, INFREQUENT_ACCESS (Infrequent Access (cheaper)).
Limitlimitnumber: How many per page, 1-50. Default 50.From 1 to 50.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "has_more": false,
    "log_group_names": [
      "/myapp/production"
    ],
    "log_groups": [
      {
        "created_at": "2026-09-29T08:00:00Z",
        "data_protection_status": null,
        "deletion_protection_enabled": false,
        "kms_key_id": null,
        "log_group_arn": "arn:aws:logs:us-east-1:123456789012:log-group:/myapp/production",
        "log_group_class": "STANDARD",
        "log_group_name": "/myapp/production",
        "metric_filter_count": 0,
        "retention_in_days": 30,
        "stored_bytes": 10240
      }
    ],
    "next_token": null
  }
}

List metrics

List the metrics in the connected region, optionally by namespace, name or dimension. Up to 500 per page.

Inputs

Namespacenamespacetext: Only this namespace, for example AWS/EC2.
Metric namemetric_nametext: Only metrics with this name.
Dimensionsdimensionsobject: Only metrics with these dimensions, as name: value. Leave a value empty to match any value of that dimension.
Active in the last 3 hoursrecently_activetrue/false: Only metrics that received data in the last 3 hours.Default: false.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "has_more": false,
    "metrics": [
      {
        "dimensions": {
          "InstanceId": "i-0123456789abcdef0"
        },
        "metric_name": "CPUUtilization",
        "namespace": "AWS/EC2"
      }
    ],
    "next_token": null
  }
}

Publish metric data point

Publish one value to a custom metric, creating the metric the first time. A new metric can take up to 15 minutes to appear in List metrics, but can be read with Get metric statistics straight away.

Inputs

NamespacenamespacetextRequired: Your namespace, for example 'MyApp'. It must not start with 'AWS/'.
Metric namemetric_nametextRequired: The metric's name, for example CPUUtilization.
ValuevaluenumberRequired: The value to record.
Unitunittext: The unit of the values. Leave empty for none.One of: Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, and 17 more.
Dimensionsdimensionsobject: The metric's dimensions as name: value pairs, exactly as published (for example InstanceId: i-0123456789abcdef0).
Timestamptimestampdate and time: When the value was measured, within the last two weeks. Leave empty for now.
High resolutionhigh_resolutiontrue/false: Store with one-second resolution instead of one minute. High-resolution metrics cost more.Default: false.

Outputs

resultobject

Example output

{
  "result": {
    "dimensions": {
      "Environment": "production"
    },
    "metric_name": "OrdersPlaced",
    "namespace": "MyApp",
    "published": true,
    "timestamp": null,
    "unit": "Count",
    "value": 3.0
  }
}

Save dashboard

Create a dashboard, or replace an existing dashboard's whole body. Three dashboards are free each month.

Inputs

Dashboarddashboard_nametextRequired: Pick a dashboard to replace, or type a new name (letters, digits, '-' and '_').
Dashboard bodydashboard_bodyobjectRequired: The dashboard as JSON: an object with a 'widgets' list. Copy one from an existing dashboard's Actions > View/edit source in the CloudWatch console.

Outputs

resultobject

Example output

{
  "result": {
    "dashboard_name": "ops",
    "saved": true,
    "validation_messages": [],
    "warning_count": 0
  }
}

Search log events

Find log events in a log group that match a filter pattern, oldest first. A page can be empty while more remain - check has_more. Setting a From time makes searches faster.

Inputs

Log grouplog_group_nametextRequired: The log group's name, for example /aws/lambda/my-function, or its ARN. Use List log groups to find one.
Filter patternfilter_patterntext: A CloudWatch filter pattern, for example ERROR, "payment declined" or { $.level = "error" }. Leave empty for every event.
Log streamslog_stream_nameslist: Only these log streams (up to 100).
Log stream prefixlog_stream_name_prefixtext: Only streams whose name starts with this. Not with Log streams.
Fromstart_timedate and time: From this time.
Toend_timedate and time: Up to this time. Leave empty for now.
Limitlimitnumber: The most events to return, 1-10000. Default 10000.From 1 to 10000.
Next tokennext_tokentext: The 'next_token' from a previous page, to read the next one.

Outputs

resultobject

Example output

{
  "result": {
    "count": 1,
    "events": [
      {
        "event_id": "38245672903463829184735643986710000000000000000000000000",
        "ingested_at": "2026-09-29T09:00:01Z",
        "log_stream_name": "web-1",
        "message": "ERROR payment declined order=1042",
        "timestamp": "2026-09-29T09:00:00Z"
      }
    ],
    "has_more": false,
    "log_group_name": "/myapp/production",
    "messages": [
      "ERROR payment declined order=1042"
    ],
    "next_token": null
  }
}

Set alarm state (test)

Force an alarm into a state to test its actions - they run as if it happened. The alarm returns to its real state at its next evaluation, usually within a minute.

Inputs

Alarm namealarm_nametextRequired: The alarm's exact name (case-sensitive).
Statestate_valuetextRequired: The state to set.One of: OK, ALARM, INSUFFICIENT_DATA.
Reasonstate_reasontextRequired: Why, as shown in the alarm's history.
Reason datastate_reason_dataobject: Optional machine-readable detail, as key: value pairs.

Outputs

resultobject

Example output

{
  "result": {
    "alarm_name": "high-cpu",
    "set": true,
    "state_value": "ALARM"
  }
}

Start Logs Insights query

Start a CloudWatch Logs Insights query over one or more log groups. Read the rows with Get query results. Defaults to the last hour. Data scanned counts toward the free 5 GB a month.

Inputs

Log groupslog_group_nameslist: The log groups to query (names or ARNs, up to 50). Not needed for SQL, which names them in FROM.
Queryquery_stringtextRequired: The query.
Fromstart_timedate and time: From this time. Leave empty for an hour ago.
Toend_timedate and time: Up to this time. Leave empty for now.
Query languagequery_languagetext: The query's language. Default Logs Insights QL.One of: CWLI (Logs Insights QL), SQL, PPL.
Row limitlimitnumber: The most rows to return, 1-10000, if the query has no limit of its own.From 1 to 10000.

Outputs

resultobject

Example output

{
  "result": {
    "end_time": "2026-09-29T09:00:00Z",
    "log_group_names": [
      "/myapp/production"
    ],
    "query_id": "12ab3456-12ab-123a-789e-1234567890ab",
    "query_language": "CWLI",
    "start_time": "2026-09-29T08:00:00Z"
  }
}

Write one or more log lines to a log stream. Events are sorted into time order; ones without a time are stamped now. Events more than 14 days old or 2 hours ahead are rejected, and the step fails only if every event was.

Inputs

Log grouplog_group_nametextRequired: The log group's name, for example /aws/lambda/my-function, or its ARN. Use List log groups to find one.
Log streamlog_stream_nametextRequired: The log stream's name within the group. No ':' or '*'.
EventseventslistRequired: The log lines. Each item is text, or an object with 'message' and an ISO-8601 'timestamp'.
Create the stream if missingcreate_stream_if_missingtrue/false: Create the log stream first if it does not exist.Default: false.

Outputs

resultobject

Example output

{
  "result": {
    "accepted_count": 2,
    "expired_count": 0,
    "first_timestamp": "2026-09-29T09:00:00Z",
    "last_timestamp": "2026-09-29T09:00:00Z",
    "log_group_name": "/myapp/production",
    "log_stream_name": "web-1",
    "rejected_count": 0,
    "too_new_count": 0,
    "too_old_count": 0
  }
}

ActionsCopy Anchor Link

Create log groupCopy Anchor Link

Inputs

Outputs

Create log streamCopy Anchor Link

Inputs

Outputs

Create or update alarmCopy Anchor Link

Inputs

Outputs

Delete alarmsCopy Anchor Link

Inputs

Outputs

Delete dashboardsCopy Anchor Link

Inputs

Outputs

Delete log groupCopy Anchor Link

Inputs

Outputs

Get alarm historyCopy Anchor Link

Inputs

Outputs

Get dashboardCopy Anchor Link

Inputs

Outputs

Get metric statisticsCopy Anchor Link

Inputs

Outputs

Get query resultsCopy Anchor Link

Inputs

Outputs

List alarmsCopy Anchor Link

Inputs

Outputs

List dashboardsCopy Anchor Link

Inputs

Outputs

List log groupsCopy Anchor Link

Inputs

Outputs

List metricsCopy Anchor Link

Inputs

Outputs

Publish metric data pointCopy Anchor Link

Inputs

Outputs

Save dashboardCopy Anchor Link

Inputs

Outputs

Search log eventsCopy Anchor Link

Inputs

Outputs

Set alarm state (test)Copy Anchor Link

Inputs

Outputs

Start Logs Insights queryCopy Anchor Link

Inputs

Outputs

Write log eventsCopy Anchor Link

Inputs

Outputs

On this page

Actions

Create log group

Create log stream

Create or update alarm

Delete alarms

Delete dashboards

Delete log group

Get alarm history

Get dashboard

Get metric statistics

Get query results

List alarms

List dashboards

List log groups

List metrics

Publish metric data point

Save dashboard

Search log events

Set alarm state (test)

Start Logs Insights query

Write log events