AWS Health Events

AWS Health Event Review

Use this skill when investigating an incident and you need to check for AWS-side service events that may be causing or contributing to the observed issue. Also use this skill when a user requests a summary report of AWS Health events over a configurable time period.

When to Use This Skill

Incident Investigation (automatic activation):

• An active incident may be caused by an AWS service disruption or degradation.
• You observe service degradation, elevated error rates, latency spikes, connection failures, throttling, or capacity issues.
• You need to determine whether an AWS-side event is the root cause or a contributing factor to the current incident.
• You want to correlate observed symptoms with known AWS Health events.

Chat Reporting (on-demand activation):

• A user requests a health event summary or report for their account.
• A user wants to review the health posture of their AWS environment over a specific time period.
• A user asks about recent AWS service issues affecting their account or region.

Prerequisites

• The account must have an AWS Business Support+, Enterprise Support, or Unified Operations support plan to access the AWS Health API.
• The agent must have permissions to call the following IAM actions:
  • health:DescribeEvents
  • health:DescribeEventDetails
  • health:DescribeAffectedEntities
  • health:DescribeEventTypes
• The AWS Health API is only available in the us-east-1 region. All API calls must target the us-east-1 endpoint regardless of where the affected resources are located.
• Health event data is available for up to 90 days. Events older than 90 days cannot be retrieved via the API.

Step 1: Gather Incident Context

Before searching Health events, extract key details from the current incident:

1. Affected AWS services — identify the service(s) experiencing issues (e.g., EC2, RDS, Lambda, ELB, ECS).
2. Timeframe — determine when the incident started and its current duration. Use ISO 8601 timestamps.
3. Affected resources — collect specific resource identifiers (instance IDs, ARNs, endpoint names, cluster names).
4. Region and availability zone — identify the AWS region and, if known, the specific availability zone(s) affected.
5. Symptoms — note the observed symptoms (latency spikes, 5xx errors, connection timeouts, throttling, capacity errors).

Use these details as filter criteria in subsequent steps.

Step 2: Search Health Events

Use the AWS Health API DescribeEvents operation to retrieve events matching the incident context. All calls must target the us-east-1 endpoint.

API call pattern

aws health describe-events \
  --region us-east-1 \
  --filter '{
    "services": ["<SERVICE_CODE>"],
    "startTimes": [{"from": "<ISO-8601-start>"}],
    "regions": ["<affected-region>"],
    "eventStatusCodes": ["open", "closed"],
    "eventTypeCategories": ["issue", "scheduledChange", "accountNotification"]
  }' \
  --max-results 100

Filtering strategies

Pagination handling

• Follow the nextToken from each response to retrieve subsequent pages.
• Continue paginating until nextToken is null or a maximum of 500 events have been collected.
• Set maxResults to 100 per page for efficient retrieval.

Step 3: Filter Relevant Events

Before retrieving full event details, filter the events returned in Step 2 to identify only those relevant to the current investigation. This avoids unnecessary DescribeEventDetails calls for events that are clearly unrelated.

Relevance filtering criteria

Evaluate each event from the DescribeEvents response using these fields (available without calling DescribeEventDetails):

Filtering rules

1. Keep events where the service matches an affected service or a related service from the Service Dependency Map.
2. Keep events where the active period (startTime to endTime, or to present if open) overlaps with the incident timeframe.
3. Keep events where the region or availabilityZone matches the incident's affected region/AZ.
4. Discard accountNotification events unless the incident context specifically suggests an account-level issue (e.g., abuse notification, certificate expiry).
5. Discard closed events that ended more than 2 hours before the incident started (unlikely to be contributing).

Result

After filtering, proceed to Step 4 only with the relevant subset of events. If all events are filtered out, report that no relevant Health events were found and suggest alternative investigation paths (see Step 7).

Step 4: Get Event Details

For each relevant event identified in Step 3, retrieve full descriptions and timelines using DescribeEventDetails.

API call pattern

aws health describe-event-details \
  --region us-east-1 \
  --event-arns '["<arn-1>", "<arn-2>", ..., "<arn-10>"]'

Batching rules

• The API accepts a maximum of 10 event ARNs per request.
• If more than 10 relevant events need details, issue multiple batched calls of up to 10 ARNs each until all relevant events are detailed.

Extract from each event detail

• Event description — the latestDescription text explaining the event.
• Timeline — start time, end time (null if ongoing), last updated time.
• Status — current status (open, closed, upcoming).
• Service and region — confirm the affected service and region.
• Event type — the category (issue, scheduledChange, accountNotification) and specific type code.

Handling failedSet

• The response contains a successfulSet and a failedSet.
• If any event ARNs appear in failedSet, report the failed ARN and error message to the operator.
• Continue processing all events from successfulSet without blocking on failures.

Step 5: Identify Affected Entities

For events with eventScopeCode of ACCOUNT_SPECIFIC, retrieve the list of affected resources using DescribeAffectedEntities.

Important: Only call DescribeAffectedEntities for ACCOUNT_SPECIFIC events. PUBLIC events do not return entity data.

API call pattern

aws health describe-affected-entities \
  --region us-east-1 \
  --filter '{"eventArns": ["<event-arn>"]}'
  --max-results 100

Entity matching

When the incident context includes specific resource identifiers:

1. Retrieve all affected entities for the event (paginate up to 500 entities per event using nextToken).
2. Perform exact string matching of each entity's entityValue against the incident context resource identifiers.
3. Present matched entities in a separate section before non-matched entities.
4. Include entity status (IMPAIRED, UNIMPAIRED, UNKNOWN, PENDING) and last updated time for each entity.

Error handling

• If DescribeAffectedEntities returns an error for a specific event ARN, report the event ARN that failed and continue processing remaining events.

Step 6: Correlate with Incident

Score each Health event for relevance to the current incident using the following criteria:

Relevance scoring