Amazon CloudWatch Events
API Reference (API Version 2015-10-07)


Creates or updates the specified rule. Rules are enabled by default, or based on value of the state. You can disable a rule using DisableRule.

If you are updating an existing rule, the rule is replaced with what you specify in this PutRule command. If you omit arguments in PutRule, the old values for those arguments are not kept. Instead, they are replaced with null values.

When you create or update a rule, incoming events might not immediately start matching to new or updated rules. Allow a short period of time for changes to take effect.

A rule must contain at least an EventPattern or ScheduleExpression. Rules with EventPatterns are triggered when a matching event is observed. Rules with ScheduleExpressions self-trigger based on the given schedule. A rule can have both an EventPattern and a ScheduleExpression, in which case the rule triggers on matching events as well as on a schedule.

Most services in AWS treat : or / as the same character in Amazon Resource Names (ARNs). However, CloudWatch Events uses an exact match in event patterns and rules. Be sure to use the correct ARN characters when creating event patterns so that they match the ARN syntax in the event you want to match.

Request Syntax

{ "Description": "string", "EventPattern": "string", "Name": "string", "RoleArn": "string", "ScheduleExpression": "string", "State": "string" }

Request Parameters

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

The request accepts the following data in JSON format.


A description of the rule.

Type: String

Length Constraints: Maximum length of 512.

Required: No


The event pattern. For more information, see Events and Event Patterns in the Amazon CloudWatch Events User Guide.

Type: String

Required: No


The name of the rule that you are creating or updating.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [\.\-_A-Za-z0-9]+

Required: Yes


The Amazon Resource Name (ARN) of the IAM role associated with the rule.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Required: No


The scheduling expression. For example, "cron(0 20 * * ? *)" or "rate(5 minutes)".

Type: String

Length Constraints: Maximum length of 256.

Required: No


Indicates whether the rule is enabled or disabled.

Type: String


Required: No

Response Syntax

{ "RuleArn": "string" }

Response Elements

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

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


The Amazon Resource Name (ARN) of the rule.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.


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


There is concurrent modification on a rule or target.

HTTP Status Code: 400


This exception occurs due to unexpected causes.

HTTP Status Code: 500


The event pattern is not valid.

HTTP Status Code: 400


You tried to create more rules or add more targets to a rule than is allowed.

HTTP Status Code: 400


Creates a rule named "test" that matches events from Amazon EC2

The following is an example of a PutRule request and response.

Sample Request

POST / HTTP/1.1 Host: events.<region>.<domain> x-amz-Date: <Date> Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature> User-Agent: <UserAgentString> Content-Type: application/x-amz-json-1.1 Content-Length: <PayloadSizeBytes> Connection: Keep-Alive X-Amz-Target: AWSEvents.PutRule { "Name": "test", "EventPattern": "{ \"source\": [\"aws.ec2\"] }" }

Sample Response

HTTP/1.1 200 OK x-amzn-RequestId: <RequestId> Content-Type: application/x-amz-json-1.1 Content-Length: <PayloadSizeBytes> Date: <Date> { "RuleArn": "arn:aws:events:us-east-1:123456789012:rule/test" }

See Also

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