# API Gateway MessageCount alarm per WebSocket route

CloudWatch alarms · Updated 17 November 2026

**Short answer:** This alarm narrows the WebSocket low-traffic check to a single route using the ApiId, Stage and Route dimensions, which require detailed metrics on the stage. It fires when the SampleCount of MessageCount for that route stays below your threshold for 10 of 10 one-minute periods.

## Route-level versus stage-level

On a WebSocket API most volume often comes from one chatty route, such as a heartbeat or presence update. If the route that carries real work (say `placeOrder` or `sendMessage`) breaks, the [stage-level MessageCount alarm](https://cloudconsole.dev/alarms/api-gateway-messagecount) barely moves. The per-route alarm watches that route alone.

| Use the stage alarm when | Use the route alarm when |
|---|---|
| You want one cheap outage signal for the whole API | A specific route carries business-critical messages |
| Detailed metrics are off | Detailed metrics are on (extra cost per route) |
| Routes have similar volume | One noisy route would hide a failure in another |

## Recommended settings

| Setting | Value |
|---|---|
| Namespace | `AWS/ApiGateway` |
| Metric | `MessageCount` |
| Dimensions | `ApiId`, `Stage`, `Route` |
| Statistic | `SampleCount` |
| Period | 60 seconds |
| Datapoints to alarm | 10 |
| Evaluation periods | 10 |
| Comparison operator | `LessThanThreshold` |
| Threshold | Depends on your situation: from that route's historical volume |

As listed in the CloudWatch [recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) reference. The `Route` value is the route key, for example `sendMessage`, or the reserved keys `$connect`, `$disconnect` and `$default`.

## Choosing a per-route threshold

Routes driven by user actions are far spikier than heartbeat routes, so a floor that works for the stage is wrong here. A method that copes with that:

- Plot the route's one-minute counts against the stage's for a week.
- If the route's share of stage traffic is stable (for example, `sendMessage` is always 10–15% of messages), a metric-math ratio alarm is more robust than a raw count.
- If you stay with the raw count, set it under the route's lowest healthy minute and accept that it will only catch a near-complete stop.
- Routes with idle minutes are poor candidates; use a longer period or a synthetic client that sends a test message every minute.

## Create it

```
# Enable detailed metrics for all routes on the stage
aws apigatewayv2 update-stage --api-id w1x2y3z4a5 --stage-name prod \
  --default-route-settings DetailedMetricsEnabled=true
```

```
# Example floor of 10 messages per minute on the sendMessage route
aws cloudwatch put-metric-alarm \
  --alarm-name chat-ws-sendmessage-low \
  --namespace AWS/ApiGateway \
  --metric-name MessageCount \
  --dimensions Name=ApiId,Value=w1x2y3z4a5 Name=Stage,Value=prod Name=Route,Value=sendMessage \
  --statistic SampleCount \
  --period 60 \
  --evaluation-periods 10 \
  --datapoints-to-alarm 10 \
  --threshold 10 \
  --comparison-operator LessThanThreshold \
  --treat-missing-data breaching \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:ops-alerts \
  --region eu-west-2
```

## When it fires

1. **Is the route still matched?** Clients may have changed the field that the route selection expression reads (for instance renaming `action`), so their messages fall through to `$default`. A rising `$default` count at the same moment confirms it.
2. **Is the integration erroring?** Check `IntegrationError` and `ExecutionError` for the route.
3. **Is the feature in use?** Rule out a front-end change that hid or removed the feature that sends this message.
4. Check route-level throttling settings; a very low route limit produces client errors instead of messages.

## Questions

### What is the Route dimension value for a WebSocket API?

The route key, such as sendMessage, or one of the reserved keys $connect, $disconnect and $default.

### Why is my route-level MessageCount alarm empty?

Detailed metrics are probably not enabled on the stage, or the route has had no traffic since they were.

### Should I alarm on $default traffic?

A sudden rise in $default can be more useful than a drop: it often means clients are sending messages that no longer match their intended route.

## When this happens away from your desk

When a single WebSocket route breaks, the API looks fine at a glance. CloudConsole, a phone app for AWS, is built to show per-route alarms and message graphs on a phone so you can see which flow stopped.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Recommended alarms for AWS services (Amazon CloudWatch User Guide)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html)
- [Amazon API Gateway documentation](https://docs.aws.amazon.com/apigateway/)

## Related

- [CloudWatch alarm for API Gateway MessageCount (WebSocket API stage)](https://cloudconsole.dev/alarms/api-gateway-messagecount)
- [API Gateway IntegrationLatency alarm per route (WebSocket API)](https://cloudconsole.dev/alarms/api-gateway-websocket-integrationlatency)
- [CloudWatch alarm for API Gateway ClientError (WebSocket API)](https://cloudconsole.dev/alarms/api-gateway-clienterror)
- [CloudWatch alarm for API Gateway ExecutionError (WebSocket API)](https://cloudconsole.dev/alarms/api-gateway-executionerror)
- [aws cloudwatch put-metric-alarm](https://cloudconsole.dev/cli/cloudwatch-put-metric-alarm)
- [CloudWatch alarm for API Gateway 4xx (HTTP API)](https://cloudconsole.dev/alarms/api-gateway-4xx)

---

Source: https://cloudconsole.dev/alarms/api-gateway-websocket-messagecount-per-route

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
