> ## 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.

# Integrate data ingestion into Stigg

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.

## Ingestion options

### Aggregated Usage API (Report Usage / Report Usage Bulk)

The most straightforward way to track usage in Stigg is through the [Report Usage](/api-and-sdks/api-reference/rest/usage-report) 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](/api-and-sdks/api-reference/mutations/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](/api-and-sdks/api-reference/rest/events-report) (see [rate limits documentation](../../faq/scale-and-high-availability/rate-limits)
* No complex aggregations, just basic operations
* Suitable for periodic reporting or direct instrumentation

### Raw Event API (Report Event)

The [Report Event](/api-and-sdks/api-reference/rest/events-report) 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 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 **100,000 events/second** on Stigg Cloud

#### Details

* Supports batch submission of events ([Report Event](/api-and-sdks/api-reference/rest/events-report))
* 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
* For 1M+ events/second, see [BYOC Early Access](#byoc-early-access)

<Card title="Need 1M+ events/second? Join the BYOC Early Access" icon="rocket" href="mailto:support@stigg.io?subject=BYOC Early Access">
  **Bring Your Own Cloud (BYOC)** deploys Stigg's ingestion and aggregation layer directly in your infrastructure, unlocking 1M+ events/second with full data sovereignty. [Contact us](mailto:support@stigg.io) to join the Early Access program.
</Card>

### 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 100,000 events/second (where API ingestion is impractical)
* 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](/api-and-sdks/api-reference/rest/usage-report)                | Simple, real-time metrics (delta/set ops)             | ✅ Yes (on call return) | ❌ No (basic operations)    | 🟢 Low             |
| [Report Usage Bulk](/api-and-sdks/api-reference/mutations/report-usage-bulk) | Same as above, but batched                            | ✅ Yes                  | ❌ No                       | 🟢 Low             |
| [Report Event](/api-and-sdks/api-reference/rest/events-report)               | Flexible metrics with dimensions, up to 100K events/s | ⚠️ \~10s delay         | ✅ Yes (count, unique, etc) | 🟢 Low             |
| Object Storage (S3/GCS)                                                      | Very high throughput, batch processing                | ❌ No (asynchronous)    | ✅ Yes                      | 🟡 Medium          |
| BYOC (Early Access)                                                          | 1M+ events/second, data sovereignty                   | ⚠️ \~1 min delay       | ✅ Yes                      | 🟡 Medium          |