# API Gateway IntegrationLatency alarm per route (WebSocket API)

CloudWatch alarms · Updated 17 November 2026

**Short answer:** This alarm watches backend response time for one WebSocket route using the ApiId, Stage and Route dimensions, firing when p90 IntegrationLatency is at or above 2,000 ms for 5 of 5 one-minute periods. It needs detailed metrics on the stage and is worth it when routes call different backends.

## When to go per route

The [stage-level IntegrationLatency alarm](https://cloudconsole.dev/alarms/api-gateway-integrationlatency) takes the p90 across every message that reached an integration. On a WebSocket API that usually means a mix of fast routes (heartbeats, presence) and slower ones (saving state, calling a payment service). Fast routes dominate the count and can hide a slow one.

Use the per-route alarm when:

- routes map to different Lambda functions or services, so one can degrade alone;
- some routes need much tighter limits than others;
- you want the alarm itself to name the failing route, instead of digging after it fires.

## Recommended settings

| Setting | Value |
|---|---|
| Namespace | `AWS/ApiGateway` |
| Metric | `IntegrationLatency` |
| Dimensions | `ApiId`, `Stage`, `Route` |
| Statistic | `p90` |
| Period | 60 seconds |
| Datapoints to alarm | 5 |
| Evaluation periods | 5 |
| Comparison operator | `GreaterThanOrEqualToThreshold` |
| Threshold | 2000.0 (milliseconds) |

Settings as given in the CloudWatch [recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) list. The `Route` value is the route key, such as `saveDocument` or `$connect`.

## Choosing a threshold per route

1. Enable detailed metrics and let a week of data build up.
2. For each route, find its typical p90 and its worst healthy p90.
3. Ask what delay a user notices for that action. A typing indicator that lags by a second feels broken; a document save taking two seconds may be fine.
4. Set the threshold between the worst healthy value and that user limit.

Routes with few messages per minute produce unreliable percentiles; either lengthen the period or add `--evaluate-low-sample-count-percentile ignore`.

## Create it

```
aws apigatewayv2 update-stage --api-id w1x2y3z4a5 --stage-name prod \
  --default-route-settings DetailedMetricsEnabled=true
```

```
aws cloudwatch put-metric-alarm \
  --alarm-name docs-ws-savedocument-p90 \
  --namespace AWS/ApiGateway \
  --metric-name IntegrationLatency \
  --dimensions Name=ApiId,Value=w1x2y3z4a5 Name=Stage,Value=prod Name=Route,Value=saveDocument \
  --extended-statistic p90 \
  --period 60 \
  --evaluation-periods 5 \
  --datapoints-to-alarm 5 \
  --threshold 2000 \
  --comparison-operator GreaterThanOrEqualToThreshold \
  --treat-missing-data notBreaching \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:ops-alerts \
  --region eu-west-2
```

## When it fires

- **Identify the integration** behind the route with `aws apigatewayv2 get-routes --api-id w1x2y3z4a5` and the target it lists.
- **Compare with the backend metric.** For a Lambda function, chart its `Duration` p90; matching curves mean the function is slow, a large gap suggests cold starts or throttling.
- **Check the `$connect` route separately.** Slow connects are often an authorizer or a database lookup on connect, and they delay every client reconnecting after a deploy.
- Look for integration errors on the same route; timeouts often appear as both high latency and errors.
- **Consider the payload.** A route whose messages suddenly carry much larger documents takes longer to process; check whether a client change increased message size.

If the route's backend is shared with other routes, expect their alarms to follow shortly; fixing the shared dependency clears them together.

## Questions

### How do I monitor latency for a specific WebSocket route?

Enable detailed metrics on the stage, then alarm on IntegrationLatency with the ApiId, Stage and Route dimensions.

### Does IntegrationLatency exist for the $connect route?

Yes, when $connect has an integration. Slow connects are worth alarming on separately because they affect every reconnecting client.

### Why 2,000 ms?

It is AWS's starting point. Most interactive WebSocket routes should use a lower value based on their own history.

## When this happens away from your desk

When one real-time feature lags, users notice before dashboards do. CloudConsole, a phone app for AWS, is built to show per-route alarms like this one with the backend's timings on a phone.

[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 IntegrationLatency (ApiId, Stage)](https://cloudconsole.dev/alarms/api-gateway-integrationlatency)
- [API Gateway MessageCount alarm per WebSocket route](https://cloudconsole.dev/alarms/api-gateway-websocket-messagecount-per-route)
- [CloudWatch alarm for API Gateway ExecutionError (WebSocket API)](https://cloudconsole.dev/alarms/api-gateway-executionerror)
- [CloudWatch alarm: Lambda Duration (p90)](https://cloudconsole.dev/alarms/lambda-duration)
- [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-integrationlatency

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