> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How-to: Ingest usage events

Zenskar lets you push usage events or pre-aggregated data via REST APIs into its ingestion layer. This integration enables real-time ingestion for billing, metrics, and reporting.

## What you send

You can send:

* **Usage events**: Individual, timestamped records of actions (for example, API calls, compute hours).
* **Aggregates**: Pre-summarized values (for example, total compute hours per day or per month).

Both types are accepted via the same ingestion endpoint.

## Set up an API endpoint

1. In the Zenskar dashboard, navigate to **Usage > Usage events**.
2. Click **+ ADD USAGE EVENT** button.
3. Fill in the following:
   * **Usage Event Name**: A descriptive label for this data stream.
   * **API Slug Endpoint**: A URL-safe identifier (alphanumeric, underscores, or dashes).
   * **Your Data Schema**: Define the JSON structure you will send.
   > 🚧 Note
   >
   > * `customer_id` and `timestamp` are required and read-only.
   > * Zenskar uses `timestamp` to order incoming records.
4. Click **ADD USAGE EVENT** to create the endpoint and corresponding ingestion pipeline.

## Example payloads

### Send a usage event

```shell theme={null}
curl -X POST https://api.zenskar.com/usage/compute_hours \
  -H "organisation: <ORG_KEY>" \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "customer_id": "cus_123",
    "timestamp": "2025-06-17T14:03:12Z",
    "data": { "cpu_usage_hours": 5 }
  }'
```

### Send an aggregate

```shell theme={null}
curl --location --request POST https://api.zenskar.com/usage/compute_hours \
  -H "organisation: <ORG_KEY>" \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "customer_id": "cus_123",
    "timestamp": "2025-06-30T23:59:59Z",
    "data": { "cpu_usage_hours_per_month": 320 }
  }'

```

<br />

## What happens next

* Zenskar stores the data in a secure, RDBMS-style table.
* Usage events must be aggregated (using SQL or the visual builder) to become billable metrics.
* Aggregates, being pre-summarized, can be used directly.
* All ingested data is available as structured tables for defining billable metrics.

## 👍 Pros and 👎 cons

| 👍 Pros                                                                                                                                        | 👎 Cons                                                                                                                                                                                |
| :--------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your data model and Zenskar are decoupled: you can change your database schema without worrying about affecting your integration with Zenskar. | Using data-ingestion APIs requires engineering effort. The integration time depends on the number of usage metrics that need to be integrated and the available engineering bandwidth. |
| Real-time data transmission from your system to Zenskar ensures that the usage data is always up-to-date.                                      |                                                                                                                                                                                        |
| Real-time data transmission from your system to Zenskar ensures quick invoice generation.                                                      |                                                                                                                                                                                        |
| Real-time usage-based entitlement tracking, monitoring, and alerts are possible.                                                               |                                                                                                                                                                                        |
| Zenskar allows you to edit usage data that has been synced.                                                                                    |                                                                                                                                                                                        |