Stigg supports multiple ingestion methods for tracking usage events, and the ideal approach depends on your event volume, architecture, and enforcement latency needs. This guide outlines when to use each method and what to consider when making your decision.Documentation Index
Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
Use this file to discover all available pages before exploring further.
Ingestion options
Aggregated Usage API (Report Usage / Report Usage Bulk)
The most straightforward way to track usage in Stigg is through the Report Usage endpoint. It 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 the Report Usage Bulk endpoint 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 Report Event (see rate limits documentation
- No complex aggregations, just basic operations
- Suitable for periodic reporting or direct instrumentation
Raw Event API (Report Event)
The Report Event endpoint is designed for tracking raw usage events, which are ingested asynchronously and processed into usage totals, typically within ~10 seconds. It allows for more flexible metering, including dimensions and advanced aggregations likecount, 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 (Report Event)
- 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 |
|---|---|---|---|---|
| Report Usage | Simple, real-time metrics (delta/set ops) | ✅ Yes (on call return) | ❌ No (basic operations) | 🟢 Low |
| Report Usage Bulk | Same as above, but batched | ✅ Yes | ❌ No | 🟢 Low |
| Report Event | Flexible metrics with dimensions | ⚠️ ~10s delay | ✅ Yes (count, unique, etc) | 🟢 Low |
| Object Storage (S3/GCS) | Very high throughput, batch processing | ❌ No (asynchronous) | ✅ Yes | 🟡 Medium |