Query Path

The query path is a fast, zero-setup, recent (≤90 days), single-region, single-event-stream operational lens over the metering SUBMISSIONS you sent to BatchMeterUsage — it answers debugging/triage questions from CloudTrail Event History. It reflects what was submitted and how the API responded — the per-record results[].status values Success/DuplicateRecord/CustomerNotSubscribed (CloudTrail lowercases response field names; the direct SDK response is PascalCase Results[].Status), and request-level exceptions like InvalidUsageDimensionException that failed a whole call — including rejected/duplicate records that were not billed.

USES (the skill queries this directly):

• CloudTrail Event History (LookupEvents) in the seller’s metering region, last ≤90 days, page-bounded and processed in memory (see “Result completeness” below).
• BASIC queries only: lookups and simple filters/counts/summaries by customer, dimension, status, or time range (the query types below).

RECOMMENDS (out of scope for this query — hand off, do not run here):

When a question lands outside the USES scope, say so — don’t return a bounded, submissions-only answer as if it were the authoritative/billed total.

CloudTrail-derived SQL analytics is the WRONG source for billing/usage analytics

Any CloudTrail-based path — CloudTrail Lake OR Athena over a (self-managed) CloudTrail trail → S3 export — analyzes SUBMISSIONS only: it includes rejected / DuplicateRecord records (NOT billed), is regional, and for Concurrent Agreements carries no productCode (no product attribution). So it is the wrong source for billing/usage analytics.

• Do NOT set up CloudTrail Lake / create-event-data-store for metering — not for analytics and not for lookups.
• For complex SQL analytics, billing-grade totals, or data older than 90 days, use SDDS data feeds: AWS pushes daily CSV (~midnight UTC, prior-day 24h) to your encrypted S3 bucket and you run your OWN Athena/ETL over the bi-temporal feeds. SDDS is enrollment-forward (NO backfill), push-only (no on-demand query/trigger API), and enrolled via a one-time MANUAL AMMP step (“Set up customer data storage”). The skill RECOMMENDS but does not run it. (Billed history for any range with no setup is also in the console “Billed Revenue” dashboard — see references/seller-reports.md.)
• A self-managed CloudTrail trail → S3 (never Lake) + Athena is acceptable ONLY for long-term raw-SUBMISSION AUDIT retention (from setup forward, no backfill) — NOT as a billing/usage-analytics source. The destination bucket stores raw BatchMeterUsage/ ResolveCustomer submission data, so it MUST be encrypted at rest with SSE-KMS (KMSKeyId on the trail, a customer-managed key) and enforce encryption in transit with a bucket policy denying aws:SecureTransport=false; also block public access and restrict read to the auditing principals.
• Do NOT reference the deprecated GenerateDataSet.

Step 1: Determine the Seller’s Metering Region

You MUST ask the user which region their application calls BatchMeterUsage from. CloudTrail Event History is regional — you MUST query the same region where the API was invoked.

Ask the seller which region their application calls BatchMeterUsage from — do not assume a fixed set. You must query CloudTrail in that same region.

Step 2: Extract Query Parameters

Parse the user’s query to identify filters:

Step 3: Run the Query Script

If --start-date is omitted, defaults to last 7 days.

Queries older than 90 days are out of scope

CloudTrail Event History (the only source this script queries) retains 90 days. Do NOT attempt to query older data with this tool. If the requested range is entirely older than 90 days, the script does not query — it returns a recommendation to use the seller-run Seller Reports / SDDS path (references/seller-reports.md): the seller completes the one-time “Set up customer data storage” step in AMMP and runs their own query/ETL over the delivered S3 feeds. If the range only partly predates 90 days, the script queries the in-window portion and notes that the older portion needs Seller Reports / SDDS.

Product-specific queries need a LicenseArn→productCode mapping

BatchMeterUsage for Concurrent Agreements (LicenseArn-based) carries no productCode, so a CloudTrail event cannot be attributed to a product from the API fields alone. Before a product-specific query (--product-code), establish a mapping from one of these, in order:

1. Single-product deployment context — pass --deployment-product-code <productCode> when the events come from a single-product stack (awsmp-<productCode>-metering/-usage).
2. CloudTrail additionalEventData — if the event carries a LicenseArn→productCode map, the script uses it automatically.
3. Subscribers table — the productCode attribute per licenseArn row can serve as the map.

If none is available, the script does NOT support the product-specific query: it explains why and offers only non-product-scoped queries (by customer, dimension, status, or time range). Legacy ProductCode-based metering carries ProductCode at the request level, so product attribution is available directly.

Step 4: Interpret Results

Query Type Selection Guide

Result completeness (bounded, in-memory fetch)

The query fetches CloudTrail Event History with LookupEvents, paginating up to --max-pages (default 20 pages × 50 = ~1000 events), then filters and aggregates in memory. A single query is a bounded window, not an exhaustive scan — a high-volume seller’s broad window can hold more events than the cap fetches.

Every result therefore carries explicit completeness signals:

• complete: true — the whole requested window was fetched (truncated: false, windowClipped: false).
• truncated: true — the page cap was hit with more events available; the result is a partial sample. fetch.pagesFetched / fetch.eventsProcessed show how much was read.
• windowClipped: true — the requested start predates the 90-day CloudTrail retention limit, so the result covers only the last 90 days (a SHORTER range than requested); the output states the covered start date. complete is false whenever the result is truncated OR clipped.

Confirm completeness before presenting a result (double-pass). Because this skill is run by an AI agent, always inspect these signals on the query output before answering. If complete is false, either (a) re-run to get a complete answer where feasible — narrow/adjust the range for a clip, or raise --max-pages / add --customer-id/--dimension/--status for truncation — and confirm the re-run is complete: true; or (b) present the result while explicitly stating it is partial (what was clipped/truncated and the covered range) and pointing to Seller Reports for the authoritative or older portion. For the aggregate query types (summary, count, top_customers) a truncated or clipped result carries an aggregateWarning — the numbers are a lower bound, not authoritative. Never report a partial result as covering the full requested range, and never quote a partial aggregate as a definitive total.

Status Explanations

Request-level exceptions (fail the whole BatchMeterUsage call — NOT per-record Results statuses; the pipeline isolates the offending record by bisection so co-batched records still meter):

• InvalidUsageDimensionException — a dimension not defined in the catalog (fix the dimension key / define it in AMMP; isolated to RejectedClientSide reason InvalidUsageDimensionException, surfaced on the BatchMeterUsageException metric).
• TimestampOutOfBoundsException — a record older than 24 hours (fix the timestamp).

Data Tiers

“Totals don’t match disbursement?” — CloudTrail shows ALL (including DuplicateRecord + rejected). Seller Reports show only billed. Difference = rejected/duplicate.

Troubleshooting

“No records found” — Wrong region, too soon (<15 min), wrong filter, or beyond 90 days.

“No errors but not billing” — Dimension mismatch (case-sensitive, no runtime error).

Script slow — Use --max-pages, --limit, or narrow date range.

For full CloudTrail CLI patterns and pagination examples, load references/query-patterns.md.