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

# Step 2: Ingest usage events via API

To process customer service consumption, Zenskar's **Usage** module utilizes a two-phase approach for API-based ingestion:

1. You will define the schema of your **usage events** in Zenskar, setting up dedicated API endpoints for each event type.
2. You will send your raw usage data to these configured endpoints.

***

## Prerequisites

<Cards columns={1}>
  <Card title="Usage events" href="https://docs.zenskar.com/docs/usage-event" icon="fa-info-circle" target="_blank">
    Usage events are granular records (e.g., an API call, a minute of video streaming). Zenskar supports flexible data ingestion methodologies, including APIs for real-time or near real-time data flow. All ingested data is stored in Zenskar's relational database management system (RDBMS) tables.
  </Card>
</Cards>

***

## 2.1: Define usage event structure

Before ingesting data, you must define the schema for each type of usage event within Zenskar. This creates specific API endpoints (slugs) to which your client system will then send the actual usage data. We will define two separate usage event types: one for **Compute Usage** and one for **Storage Usage**.

<Tabs>
  <Tab title="Dashboard">
    You will configure two separate usage event definitions through the Zenskar dashboard using the "Add Usage Event" UI.

    1. Log in to your Zenskar dashboard.
    2. Navigate to the **Usage** > **Usage Events**.
    3. Click "+ ADD USAGE EVENT" to open the configuration form.

    **First definition: For compute usage events**

    * **Usage Event Name:** Enter `Compute events`. This will create the endpoint `https://api.zenskar.com/usage/compute_events`.
    * **API Slug Endpoint:** Will display `https://api.zenskar.com/usage/compute_events`.
    * **Root Fields:**
      * `customer_id` (Data type: `String`)
      * `timestamp` (Data type: `DateTime64`)
    * **Your Data Schema:**
      * Click **+ ADD NEW DATA FIELD** and add:
        * `cpu_hours_consumed` (Data type: `Float64`)
        * `region` (Data type: `String`)
    * **Order By:** Ensure `timestamp` is selected or entered.
    * Review the "Data Schema Preview" and click "ADD USAGE EVENT".

    **Second definition: For storage usage events**

    * **Usage Event Name:** Enter `Storage events`. This will create the endpoint `https://api.zenskar.com/usage/storage_events`.
    * **API Slug Endpoint:** Will display `https://api.zenskar.com/usage/storage_events`.
    * **Root Fields:**
      * `customer_id` (Data type: `String`)
      * `timestamp` (Data type: `DateTime64`)
    * **Your Data Schema:**
      * Click "ADD NEW DATA FIELD" and add:
        * `storage_gb_month` (Data type: `Float64`)
        * `storage_tier` (Data type: `String`)
    * **Order By:** Ensure `timestamp` is selected or entered.
    * Review the "Data Schema Preview" and click "ADD USAGE EVENT".
  </Tab>

  <Tab title="API (alternative for automation)">
    You can also programmatically define your usage event structures using Zenskar's **Create usage event** API. This API is typically `POST https://api.zenskar.com/rawmetrics`.

    **First Definition: For Compute Usage Events**

    ```bash theme={null}
    curl -X POST 'https://api.zenskar.com/rawmetrics' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: <your-api-key>' \
    -d '{
    		"name": "Compute events",
    		"api_slug": "compute_events",
    		"dataschema": {
        		"data": {
            		"cpu_hours_consumed": "Float64",
            		"region": "String"
        		},
        		"timestamp": "DateTime64",
        		"customer_id": "String"
    		},
    		"column_order": [
        		"timestamp"
    		]
    }
    ```

    **Second Definition: For Storage Usage Events**

    ```bash theme={null}
    curl -X POST 'https://api.zenskar.com/rawmetrics' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: <your-api-key>' \
    -d '{
    		"name": "Compute events",
    		"api_slug": "compute_events",
    		"dataschema": {
        		"data": {
            		"storage_gb_month": "Float64",
            		"storage_tier": "String"
        		},
        		"timestamp": "DateTime64",
        		"customer_id": "String"
    		},
    		"column_order": [
        		"timestamp"
    		]
    }'
    ```

    *(Refer to the[Zenskar Create Usage Event API documentation](https://docs.zenskar.com/reference/create-usage-event) for the exact schema and how to specify the event name.)*
  </Tab>
</Tabs>

***

## 2.2: Ingest usage events

Once you have defined your usage event structures (e.g., compute\_events and storage\_events in the previous sub-step), your client system can now push actual usage data to the specific API endpoint generated for each, or upload it directly via the Zenskar Dashboard.

<Tabs>
  <Tab title="Dashboard">
    You can manually add single usage events or upload them in bulk via CSV directly through the Zenskar dashboard. This uses the usage event structure you defined in Step 2.1.

    1. Log in to your Zenskar dashboard.
    2. Navigate to the **Usage module**, then select the specific **Usage Event** you want to ingest data for (e.g., "compute\_events" or "storage\_events").
    3. To add data:
       * **Upload CSV:** Click the "UPLOAD CSV" button. You will need a CSV file formatted according to the schema you defined in Step 2.1 *for that specific usage event type* (e.g., if uploading for `compute_events`, columns for `customer_id`, `timestamp`, `cpu_hours_consumed`, `region`).
       * **Add Single Event:** Look for an option to "Add single event" (often a button or a menu item near the "Upload CSV" button). This will open a form where you can manually enter details for a single usage event based on its defined schema.
    4. After uploading or adding, the events will appear in the "Events Table" for the selected usage event type.
  </Tab>

  <Tab title="API">
    You will send usage data to the specific endpoint for **compute events** and another for **storage events**, ensuring the payload adheres to the schema defined for that endpoint.
    **Sample usage events (using`curl`):**

    **Compute usage event (e.g., CPU hours consumed):**

    ```bash theme={null}
    curl -X POST 'https://api.zenskar.com/usage/compute_events' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: <your-api-key>' \
    -d '{
        "customer_id": "cust_7d2f9b8c-1e2a-4c3d-9f0e-1a2b3c4d5e6f",
        "timestamp": "2025-07-28T10:00:00Z",      
        "data": {
            "cpu_hours_consumed": 10.5,
            "region": "us-east-1"
        }
    }'
    ```

    **Storage usage event (e.g., GB-Months consumed):**

    ```bash theme={null}
    curl -X POST 'https://api.zenskar.com/usage/storage_events' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: <your-api-key>' \
    -d '{
        "customer_id": "cust_7d2f9b8c-1e2a-4c3d-9f0e-1a2b3c4d5e6f",
        "timestamp": "2025-07-28T10:00:00Z",
        "data": {
            "storage_gb_month": 500.0,
            "storage_tier": "standard"
        }
    }'
    ```

    *(Replace`YOUR_ZENSKAR_API_KEY` and `cust_7d2f9b8c-1e2a-4c3d-9f0e-1a2b3c4d5e6f` with your actual values.)*
  </Tab>
</Tabs>