Ingestion options
Aggregated Usage API (reportUsage / reportUsageBulk)
The most straightforward way to track usage in Stigg is through the reportUsage API. This method supports real-time entitlement enforcement and usage updates immediately after the API call succeeds. It’s ideal for simpler use cases and lower-volume environments, and supports either delta incrementation or absolute “set” operations.
You can also use reportUsageBulk to submit usage for multiple customers or metrics in a single request.
Best for
- Simple metrics (e.g., API calls, seats used)
- Real-time enforcement with minimal complexity
- Moderate throughput needs
Details
- Supports delta (
+X) or set (=Y) operations - Entitlements are updated immediately after the call returns
- Lower rate limits than
reportEvent(see rate limits documentation) - No complex aggregations—just basic operations
- Suitable for periodic reporting or direct instrumentation
Raw Event API (reportEvent)
The reportEvent API is designed for tracking raw usage events, which are ingested asynchronously and processed into usage totals—typically within ~10 seconds. This method allows for more flexible metering, including dimensions and advanced aggregations like count, unique, sum, min, max, etc. It’s especially useful when you want to segment usage (e.g., per endpoint, region, or feature) and support more dynamic use cases.
You can report a single event or a batch of events using this endpoint.
Best for
- Usage metering based on raw events
- Complex aggregation and dimensional analysis
- Peak volume of up to 1000 events/second
Details
- Supports batch submission of events (
reportEvent) - Events include dimensions and metadata
- Usage updates asynchronously (~10s delay)
- Powerful aggregation capabilities
- Suitable for both real-time and pre-aggregated reporting
- The endpoint accepts a list of events in one request (batch or single event)
- Rate limits apply to the number of events per second
Object Storage Ingestion (S3 / GCS)
For extremely high-volume systems, Stigg supports asynchronous ingestion from cloud object storage such as Amazon S3 or Google Cloud Storage. This is ideal if you’re already writing usage events to storage and want Stigg to pull and process the data on a schedule. This approach is production-ready and suitable for customers with billions of monthly events and batch-oriented architectures.Best for
- Event volumes exceeding 1000 events/second
- Existing pipelines writing usage to S3/GCS
- Asynchronous and large-scale ingestion
Details
- You write usage events to a pre-defined format in S3 or GCS
- Stigg processes the data on a scheduled basis
- Suitable for nightly or hourly batch jobs
- Requires provisioning access and initial pipeline setup
Summary
| Ingestion Method | Best For | Real-Time Enforcement | Aggregation Support | Engineering Effort |
|---|---|---|---|---|
reportUsage | Simple, real-time metrics (delta/set ops) | ✅ Yes (on call return) | ❌ No (basic operations) | 🟢 Low |
reportUsageBulk | Same as above, but batched | ✅ Yes | ❌ No | 🟢 Low |
reportEvent | Flexible metrics with dimensions | ⚠️ ~10s delay | ✅ Yes (count, unique, etc) | 🟢 Low |
| Object Storage (S3/GCS) | Very high throughput, batch processing | ❌ No (asynchronous) | ✅ Yes | 🟡 Medium |