AWS Health API: A Developer's Integration Guide

The AWS Health API gives you programmatic access to account-specific AWS service events — scheduled maintenance, service disruptions, and resource-level impacts that never appear on the public status page. The catch: you need a paid AWS Support plan at the Business, Enterprise On-Ramp, Enterprise, or Unified Operations tier. Call it without one and you get SubscriptionRequiredException immediately, regardless of your IAM permissions.

Three things to do right now:

Confirm your account’s Support plan in the AWS Console before writing a single line of integration code.
Use an official AWS SDK (boto3, AWS SDK for JavaScript v3, or AWS SDK for Java) rather than raw REST calls.
Authenticate with temporary credentials from AWS STS, not long-term access keys.

Key constraints at a glance:

Access gate: Business Support or higher required
Auth method: Signature Version 4 (SigV4), handled automatically by SDKs
Endpoint: Resolve the global endpoint at runtime — never hardcode a regional one
Org view: Requires AWS Organizations and separate enablement steps

Key Takeaways

The AWS Health API provides account-specific event data gated by paid Support plans, authenticated via SigV4, and best consumed through official SDKs targeting the global endpoint resolved at runtime.

Point	Details
Support plan required	Business, Enterprise On-Ramp, Enterprise, or Unified Operations — no workaround via IAM.
Use SDKs, not raw REST	boto3, AWS SDK for JavaScript v3, and AWS SDK for Java handle SigV4 signing and pagination automatically.
Resolve endpoint at runtime	Use `global.health.amazonaws.com` via DNS — never hardcode a regional endpoint.
Prefer temporary credentials	Use AWS STS roles or instance profiles instead of long-term access key/secret pairs.
Org-level aggregation	Enable organizational view from the management account; use `DescribeEventsForOrganization` for multi-account visibility.

What does the AWS Health API actually return?
What access do you need before calling the API?
How do you authenticate and target the right endpoint?
What are the core API operations and how do you use them?
Which SDKs and tools get you started fastest?
How do you wire Health events into incident workflows?
How do you troubleshoot common AWS Health API errors?
How IT-Magic uses the AWS Health API during large migrations
A note from the migration team
Official docs and helpful links
Sources
FAQ

What does the AWS Health API actually return?

The API returns events scoped to your account or organization — not the generic service-level status anyone can see. That distinction matters more than it sounds.

The public AWS Health Dashboard is free, unauthenticated, and shows broad service interruptions with a 12-month history. It tells you “EC2 is degraded in us-east-1.” The Health API tells you which of your specific instances are affected, when the impact started, what AWS is doing about it, and whether a scheduled maintenance window is coming for your resources. Those are fundamentally different data sets.

It also differs from instance-level health checks. ELB and EC2 health checks tell you whether a target is responding to pings. The Health API reports service-side events — things happening on AWS’s infrastructure that affect your resources, plus planned changes like hardware retirements or certificate rotations. You need both, but for different reasons.

Common event fields you’ll work with:

eventTypeCode — the event category (e.g., AWS_EC2_INSTANCE_RETIREMENT_SCHEDULED)
statusCode — open, closed, or upcoming
affectedEntities — the specific ARNs or resource IDs in your account
startTime / endTime — impact window
eventScopeCode — ACCOUNT_SPECIFIC, PUBLIC, or NONE

Pro Tip: Filter by eventScopeCode: ACCOUNT_SPECIFIC in your queries. Public events are informational; account-specific ones require action. Mixing them without filtering inflates alert volume and buries the signals that actually matter.

What access do you need before calling the API?

Support-plan gating is enforced at the service level, not the IAM level. That means a perfectly configured IAM policy with health:* permissions still returns SubscriptionRequiredException if the account runs on Basic or Developer Support. No workaround exists — you need to upgrade the Support plan first.

Plans that unlock API access:

Business Support
Enterprise On-Ramp
Enterprise Support
Unified Operations (AWS Managed Services)

Calling the AWS Health API from an account without an eligible paid Support plan returns SubscriptionRequiredException — this error is enforced at the service level and cannot be bypassed with IAM policies, SCPs, or resource-based permissions. Upgrade the Support plan first, then validate IAM.

UnauthorizedException, by contrast, means your credentials are valid but your IAM policy lacks the required health:Describe* permissions. These two errors have different fixes, so reading the error code carefully saves time.

For credentials, AWS recommends temporary credentials issued by AWS STS (via IAM roles, instance profiles, or federated identity) over long-term access key/secret pairs. Long-term keys that rotate infrequently are a security liability, especially in automated pipelines that call the Health API on a schedule.

Organizational view adds another layer. To aggregate events across all accounts in an AWS Organization, you must enable organizational view from the management account, and the IAM principal calling org-level operations needs permissions in that management account. The relevant actions are health:EnableHealthServiceAccessForOrganization and health:DescribeEventsForOrganization. Member accounts cannot enable this themselves.

How do you authenticate and target the right endpoint?

AWS Health uses SigV4 for all API requests — the same signing process used across most AWS services. If you’re using an SDK, this is handled for you automatically. If you’re making raw HTTPS calls, you’re signing request headers manually, which is error-prone and rarely worth the effort.

The endpoint situation is less obvious. The Health API uses an active-passive multi-Region architecture. At any given time, one regional endpoint is active and holds the latest event data; the other is passive. AWS can shift which region is active, so hardcoding health.us-east-1.amazonaws.com is a mistake — you may end up reading from the passive endpoint and getting stale or missing data.

The correct approach: resolve the global high-availability endpoint (global.health.amazonaws.com) at runtime via DNS. The CNAME resolves to the currently active regional endpoint. SDKs configured with the global endpoint handle this automatically.

Pro Tip: Run nslookup global.health.amazonaws.com or dig global.health.amazonaws.com before your integration goes to production. Confirm the CNAME resolves to a regional endpoint and that your network path allows outbound HTTPS to it. This one check prevents a class of silent failures where calls succeed but return incomplete event data.

For high-availability endpoint design patterns, the principle is the same as any active-passive setup: discover the active node dynamically rather than baking in a static address.

What are the core API operations and how do you use them?

The AWS Health API Reference defines a focused set of operations. Here’s how they map to real tasks:

Operation	Key Input Filters	Typical Use
`DescribeEvents`	`filter` (service, region, eventType, status, dates)	List events affecting your account; paginate with `nextToken`
`DescribeEventDetails`	`eventArns` (up to 10)	Fetch full event description and metadata for specific events
`DescribeAffectedEntities`	`filter.eventArns`, `filter.entityValues`	Find which resources in your account are impacted
`DescribeEventTypes`	`filter.services`, `filter.eventTypeCategories`	Discover available event type codes for filtering
`DescribeEventsForOrganization`	`organizationAccountIds`, `filter`	Aggregate events across all accounts in an AWS Organization
`DescribeAffectedAccountsForOrganization`	`eventArn`	List which member accounts are affected by a specific org event

A typical developer workflow runs in sequence: call DescribeEvents with a date range and eventScopeCode: ACCOUNT_SPECIFIC to get a list of event ARNs, then call DescribeEventDetails on those ARNs to get the full description, then call DescribeAffectedEntities to map impact to specific resources.

Pagination matters. DescribeEvents returns up to 10 events per page by default. Always check for nextToken in the response and loop until it’s absent. Skipping this step silently truncates your event list.

Throttling is real. The Health API has per-account request rate limits. Build exponential backoff into any polling loop — the AWS SDK retry configuration handles this automatically when you set max_attempts and mode: "adaptive".

Pro Tip: For Python, set Config(retries={"max_attempts": 10, "mode": "adaptive"}) when creating your boto3 Health client. For JavaScript v3, use the @aws-sdk/middleware-retry package with AdaptiveRetryStrategy. Both handle throttling without custom retry logic.

A minimal boto3 call looks like this:

import boto3
from botocore.config import Config

client = boto3.client(
    "health",
    region_name="us-east-1",
    endpoint_url="https://global.health.amazonaws.com",
    config=Config(retries={"max_attempts": 10, "mode": "adaptive"})
)

paginator = client.get_paginator("describe_events")
for page in paginator.paginate(
    filter={"eventScopeCode": "ACCOUNT_SPECIFIC", "statusCodes": ["open"]}
):
    for event in page["events"]:
        print(event["eventTypeCode"], event["statusCode"])

The JavaScript v3 equivalent uses HealthClient from @aws-sdk/client-health with the same global endpoint and the paginateDescribeEvents helper.

Which SDKs and tools get you started fastest?

Use an official AWS SDK. That’s the short answer. AWS recommends SDKs specifically because they handle SigV4 signing and pagination automatically — two of the most common sources of integration failures when developers go the raw REST route.

The three SDKs with solid Health API support:

boto3 (Python): The most commonly used option for Health integrations. The get_paginator interface makes pagination trivial.
AWS SDK for JavaScript v3: Modular, tree-shakeable, and ships with @aws-sdk/client-health. Works in Lambda and Node.js environments.
AWS SDK for Java: Preferred in enterprise environments running Spring Boot or other JVM stacks.

The AWS CLI works well for ad-hoc queries and runbook validation:

aws health describe-events 
  --filter eventScopeCode=ACCOUNT_SPECIFIC,statusCodes=open 
  --region us-east-1 
  --endpoint-url https://global.health.amazonaws.com 
  --output json

Add --no-paginate to pull all pages automatically, or pipe through jq to extract specific fields. The --query flag filters output inline without external tools.

AWS Health Aware is worth knowing about if you need a working integration in hours rather than days. It’s a sample application from AWS that connects Health events to Slack, JIRA, ServiceNow, and other tools out of the box. You deploy it into your account, configure the destinations, and it starts routing events immediately. It’s not production-hardened for every enterprise requirement, but as a prototype or a starting point for a custom integration, it cuts setup time significantly.

Raw REST calls are occasionally necessary — air-gapped environments, custom runtimes, or languages without an official SDK. In those cases, you’re implementing SigV4 signing yourself, which means computing HMAC-SHA256 signatures over a canonical request string. It works, but the implementation surface for bugs is large. Use a well-tested SigV4 library if one exists for your language before rolling your own.

How do you wire Health events into incident workflows?

The recommended architecture for production incident pipelines:

Ingest: Poll DescribeEvents on a schedule (every 1–5 minutes) or use Amazon EventBridge with the AWS Health event source to receive events in near real-time without polling.
Process: Route events to a Lambda function that enriches each event with DescribeEventDetails and DescribeAffectedEntities data.
Filter: Apply eventScopeCode, service, and region filters to drop noise. Only route ACCOUNT_SPECIFIC events with statusCode: open to alerting channels.
Notify: Publish enriched payloads to Amazon SNS, which fans out to Slack, PagerDuty, or email. For JIRA/ServiceNow, invoke a second Lambda that creates or updates tickets.
Correlate: Tag each incident record with the event ARN and affected entity ARNs so you can correlate Health events with CloudWatch alarms on the same resources.

EventBridge is the cleaner option if your account supports it. AWS Health publishes events directly to the default event bus, so you can write EventBridge rules that match specific detail-type values (like "AWS Health Event") and route them to targets without any polling infrastructure.

For multi-account setups, aggregate with DescribeEventsForOrganization from the management account. This gives you a single view of all open events across your organization, which is far more useful than polling each member account separately.

Deduplication matters in polling architectures. Store processed event ARNs in DynamoDB or ElastiCache with a TTL matching your event retention window. On each poll cycle, skip ARNs you’ve already processed.

Pro Tip: Combine Health events with CloudWatch metrics on the affected resources to score incident severity. The same event on an idle dev instance is a P3. Health events alone don’t tell you that — the metric context does.

How do you troubleshoot common AWS Health API errors?

Most failures fall into three categories:

SubscriptionRequiredException: The account’s Support plan is Basic or Developer. Fix: upgrade the plan. IAM changes will not resolve this.
UnauthorizedException: Valid credentials, missing IAM permissions. Add health:Describe* to the calling principal’s policy.
TooManyRequestsException: You’re hitting the per-account rate limit. Fix: add exponential backoff, reduce polling frequency, or cache results between cycles.

Common implementation mistakes that produce subtle failures rather than hard errors:

Hardcoding health.us-east-1.amazonaws.com instead of the global endpoint — calls succeed but may return stale data from the passive region.
Using long-term access keys in Lambda environment variables — works until the key is rotated or compromised.
Forgetting to enable organizational view from the management account before calling DescribeEventsForOrganization.
Filtering only on eventScopeCode: PUBLIC and wondering why account-specific events don’t appear.

When DescribeEventsForOrganization returns an empty list despite known active events, the most common cause is that organizational view was never enabled. Run aws health describe-health-service-status-for-organization to check. If the response shows healthServiceAccessStatusForOrganization: DISABLED, run aws health enable-health-service-access-for-organization from the management account.

Quick diagnostic checklist:

Verify Support plan tier in the AWS Console under Account > Support.
Test IAM permissions with aws iam simulate-principal-policy for health:DescribeEvents.
Resolve global.health.amazonaws.com via DNS and confirm the active regional endpoint.
Check response headers for x-amzn-RequestId — present on throttled responses too, useful for AWS Support cases.
Inspect nextToken in paginated responses — a missing loop here silently truncates results.

How IT-Magic uses the AWS Health API during large migrations

During a migration of a high-traffic eCommerce platform to AWS, the team at IT-Magic needed visibility into service-side events that could affect the cutover window. Application health checks told them whether the new environment was responding. They needed something different: advance notice of AWS-side maintenance, resource retirements, or regional degradations that could invalidate the migration timeline.

The integration IT-Magic built covered three layers. First, org-level aggregation via DescribeEventsForOrganization from the management account, giving the migration team a single pane across the source and destination accounts simultaneously. Second, an EventBridge rule routing AWS_EC2_* and AWS_RDS_* events to a Lambda function that created incidents in the team’s ticketing system automatically, with affected entity ARNs pre-populated. Third, a rollback trigger: if a Health event with statusCode: open appeared on a resource in the migration target account during the cutover window, the runbook flagged it for human review before proceeding.

The outcome was faster time-to-detect for infrastructure-side issues and cleaner separation between “our application broke” and “AWS had a service event.” That distinction alone reduced escalation time during the migration window.

A checklist you can adapt for your own migration runbook:

Enable organizational view from the management account before migration day.
Create EventBridge rules scoped to the services and regions in your migration scope.
Pre-populate your incident template with eventArn and affectedEntities fields.
Set a polling interval of 2 minutes or less during active cutover windows.
Define a clear decision rule: which Health event types trigger a rollback hold vs. a watch-and-proceed.

You can see more detail on how IT-Magic structures migration execution in the case studies.

A note from the migration team

Health events changed how we think about migration risk. Before wiring the API into our runbooks, we were reactive — we’d find out about an AWS service event the same way everyone else did, from the public dashboard, usually after someone noticed something wrong. With account-specific event data flowing into our incident pipeline, we catch infrastructure-side issues before they surface as application errors.

That said, the Health API is not a replacement for application health checks or CloudWatch monitoring. It tells you what AWS is doing to your infrastructure. It does not tell you whether your application is handling it correctly. The monitoring stack needs both layers. Teams that treat Health events as their primary observability signal end up with blind spots on the application side — and that’s where most production incidents actually originate.

If you’re running complex migrations or managing multi-account environments and want a managed SRE team to operate these workflows for you, IT-Magic’s DevOps-as-a-Service covers Health-event-driven incident response as part of its standard runbooks.

Official docs and helpful links

The sources below are the authoritative references for everything covered in this guide:

AWS Health API Reference — complete operation definitions, request/response schemas, and error codes
AWS Health User Guide — endpoint guidance, SigV4 signing, SDK recommendations, and organizational view setup
AWS Health Documentation hub — entry point for all Health docs including concepts, terms, and CLI reference
AWS Health Dashboard — Service health — public status page and 12-month service history (no sign-in required)
AWS Health API Reference (PDF) — downloadable full API reference including all org-level operations
AWS Health Aware on GitHub — sample app for routing Health events to Slack, JIRA, and ServiceNow

Sources

FAQ

Does AWS have a Health API?

Yes. The AWS Health API provides programmatic access to account-specific service events, scheduled maintenance, and resource-level impacts. It requires a paid AWS Support plan at the Business tier or higher.

Is the AWS Health API free to use?

The API itself has no separate charge, but access requires a paid AWS Support plan (Business, Enterprise On-Ramp, Enterprise, or Unified Operations). Basic and Developer Support plans do not include API access.

What is the difference between the AWS Health API and the public Health Dashboard?

The public AWS Health Dashboard shows broad service status and is free and unauthenticated. The Health API returns account-specific events tied to your actual resources, including affected entity ARNs and planned maintenance details that never appear on the public page.

What error do you get without the right Support plan?

Calling the AWS Health API without an eligible Support plan returns SubscriptionRequiredException. This error is enforced at the service level and cannot be resolved by adjusting IAM policies.

Is AWS owned by Jeff Bezos?

AWS (Amazon Web Services) is a subsidiary of Amazon.com, Inc., a publicly traded company. Jeff Bezos founded Amazon and served as CEO until recently; he remains executive chairman. Amazon’s shareholders collectively own the company, not any single individual.

AWS Health API: A Developer’s Integration Guide