Scan Aggregation

How individual events become billable scans.

Overview

Multiple hook events can constitute a single “scan” for billing purposes.

Aggregation Rules

Time Window

Events within 30 seconds of each other are grouped:

Event 1: 10:00:00
Event 2: 10:00:15  → Same scan
Event 3: 10:00:45  → New scan

Same Action

Events for the same action type are grouped:

Event 1: chat, tokens=500
Event 2: chat, tokens=750  → One scan, 1250 tokens

Different Actions

Different action types create separate scans:

Event 1: chat     → Scan A
Event 2: complete → Scan B

Violation Detection

During aggregation, we detect:

• Retry loops - Same request repeated 3+ times
• Token bloat - Single event with excessive tokens
• Timeout chains - Sequential timeout errors

Implementation

Aggregation runs via Lambda triggered by SQS:

1. Receive event batch
2. Group by user + time window
3. Create or update scan record
4. Run violation detection
5. Update usage counters