How-to: Ingest usage events

​

What you 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).

​

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

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

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 }
  }'

​

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