API Analytics and Metering

The Blind Spot in Your API Gateway Config

Engineers often drop an API Gateway REST API into production and assume the built-in metrics are enough. They aren't. You get request counts and 5xx errors, but you have zero visibility into per-customer consumption, quota enforcement, or billing-ready usage data. If you're running a SaaS API, this is a leak. You're giving away compute and bandwidth to users who never pay, and you have no mechanism to throttle them based on a usage plan.

The complexity lies in the distinction between simple rate limiting and metering. Rate limiting protects your infrastructure; metering protects your revenue. Without a Usage Plan, you can't distinguish between a Free tier user and a paying Enterprise customer. You're forced to hack together middleware that checks headers and returns 429s, which is fragile and hard to audit. We've seen teams ship APIs with no usage plans, no API keys for metering, and no CloudWatch RUM integration for frontend telemetry. The result is a bill from AWS that spikes while revenue stays flat, and a customer support team drowning in "why is my API slow?" tickets that turn out to be quota violations.

Why "Free Tier" Thinking Costs You Real Dollars

Ignoring metering isn't just a billing headache; it's an architecture debt that compounds. When you don't enforce quotas, a single misconfigured client or a malicious scraper can hammer your endpoints. Without a usage plan, you can't throttle based on a customer tier. You're left with binary choices: block the IP (and lose the customer) or let the request through (and eat the cost).

Consider the downstream impact. If you're selling API access, you need to map usage to a billing record. AWS Marketplace metering requires precise usage records ^[5]. If your API Gateway isn't configured with a Usage Plan and API Key association, you can't generate those records. You end up with manual CSV exports, spreadsheet reconciliation, and a high risk of underbilling. Every hour your engineering team spends manually auditing logs instead of building features is a direct drag on velocity.

And if you miss a quota violation, your infrastructure costs scale linearly with abuse, destroying your margins. The operational overhead of managing API keys across multiple environments—dev, staging, prod—without Infrastructure as Code (IaC) is a recipe for drift. You might have a usage plan defined in CloudFormation, but if the UsagePlanKey association is missing or pointing to the wrong stage, your metering is blind. This isn't theoretical; it's a common failure mode when teams treat metering as an afterthought rather than a core component of their API architecture.

A SaaS Team's Usage Plan Headache

Imagine a team shipping a data enrichment API. They start with a single REST API and a flat rate. As customers sign up, they need tiered access: Free, Pro, and Enterprise. The engineering lead tries to hack this together with custom middleware, checking headers and returning 429s when limits are hit. It works for a while, until they need to support AWS Marketplace billing.

According to AWS documentation, you can package APIs in a usage plan and sell the plan as a SaaS product through AWS Marketplace ^[8]. But to do that, the API key must be the source of metering requests according to a usage plan, typically read from the X-API-Key header ^[3]. The middleware approach breaks down because the billing integration expects the gateway to handle the key association and quota enforcement natively.

The team eventually realizes they need to provision Usage Plans, API Keys, and UsagePlanKey associations using Infrastructure as Code. They need a GetUsagePlans command to validate their configuration across environments ^[2]. They need to configure QuotaSettings (limit, offset, period) and ThrottleSettings (rateLimit, burstLimit) precisely to match their pricing tiers ^[1].

Without a canonical workflow, every deployment is a gamble. A missing UsagePlanKey association means a paying customer gets throttled or, worse, gets no quota at all. A misconfigured CloudFormation stack for the AWS::ApiGateway::RestApi ^[6] can leave metering disabled. This is the exact friction we solved. We built this pack so you don't have to debug missing associations or manually reconcile usage plans in the console.

Metering That Bills Accurately and Scales Automatically

Once you install the API Analytics and Metering Pack, the ambiguity disappears. You get a production-grade workflow that provisions Usage Plans, API Keys, and Stage associations via CloudFormation. Your API Gateway starts enforcing quotas based on the QuotaSettings you define, and throttling kicks in at the ThrottleSettings limits ^[1].

For frontend telemetry, the pack includes a TypeScript configuration module for the CloudWatch RUM Web client. This gives you real-time visibility into errors, performance, and HTTP requests from the browser side, with custom plugin support and session sampling. You can pair this with Developer Onboarding Experience to automate API key provisioning and trial access setup, ensuring every new customer hits the ground running with the right quota.

The pack also includes executable scripts for provisioning and validation. deploy-metering.sh creates the usage plan, generates the API key, and associates them, exiting non-zero on failure. validate-metering.sh queries existing usage plans and keys, verifying quota limits and throttle rates match expected values. This means you can integrate metering checks into your CI/CD pipeline, catching configuration drift before it hits production.

If you're also managing API Gateway patterns like routing or plugins, this pack integrates seamlessly, ensuring your metering logic doesn't conflict with your gateway configuration. For clients consuming your API, consider SDK Generation Pipeline to embed metering headers automatically, reducing the burden on your API consumers.

When you need API Versioning Strategy, ensure your usage plans are scoped to specific stages, allowing you to meter different versions of your API independently. Maintain your configuration as code alongside Docs-as-Code with Docusaurus to keep your API documentation synchronized with your metering policies. And before you ship, validate your metering logic in isolation using API Sandbox Environment to simulate usage patterns and verify quota enforcement without risking production traffic.

What's in the API Analytics and Metering Pack

• skill.md — Orchestrator skill that defines the workflow for implementing API analytics and metering. It instructs the AI to use the templates for infrastructure, the scripts for provisioning/validation, the references for canonical AWS knowledge, and the examples for architectural patterns.
• templates/usage-plan-cfn.yaml — Production-grade CloudFormation template that provisions an API Gateway Usage Plan, API Key, and UsagePlanKey association. Includes configurable quota and throttle settings based on AWS API Gateway specifications.
• templates/rum-web-config.ts — TypeScript configuration module for the CloudWatch RUM Web client. Implements telemetry selection, custom plugin loading, cookie handling, and session sampling as defined in the AWS RUM Web documentation.
• scripts/deploy-metering.sh — Executable bash script that provisions metering infrastructure using the AWS CLI. Creates a usage plan with specified quota/throttle, generates an API key, and associates them. Validates output and exits non-zero on failure.
• scripts/validate-metering.sh — Validator script that queries existing API Gateway usage plans and keys. Verifies quota limits, throttle rates, and stage associations match expected values. Exits with code 1 if validation fails or resources are missing.
• references/api-gateway-metering.md — Canonical reference documenting API Gateway metering mechanics. Covers Usage Plan structure, QuotaSettings (limit, offset, period), ThrottleSettings (rateLimit, burstLimit), API Stage associations, and billing integration via AWS Marketplace product codes.
• references/cloudwatch-rum-web.md — Canonical reference for CloudWatch RUM Web client implementation. Details telemetry types (errors, performance, http), custom plugin architecture, session sampling, cookie policies, and recording custom/page-view events.
• examples/tiered-metering-setup.md — Worked example demonstrating a SaaS tiered metering architecture. Shows how to configure Free, Pro, and Enterprise usage plans with distinct quotas, throttle limits, and API key distribution strategies.

Stop Guessing, Start Metering

You don't have to manually reconcile usage plans or debug missing API keys. Upgrade to Pro to install the API Analytics and Metering Pack and ship with confidence. Your API Gateway will enforce quotas, throttle abuse, and generate billing-ready records out of the box. Stop guessing, start metering.