Sending Usage Events

How to send usage events to Quivly and understand the event schema

To track customer activity, send usage events to Quivly’s Events API. This guide explains the event schema, required and optional fields, aggregation strategies, and best practices for reliable ingestion.

Event Schema

Here’s an example of a request to send usage events:

curl -X POST https://api.quivly.com/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "abc-123",
        "customer_id": "pied-piper",
        "event_code": "api_call",
        "event_type": "credit",
        "created_at": "2025-03-25T12:00:00Z",
        "event_properties": { 
          "tokens": "300",
          "status_code": 200,
          "region": "us-west-1",
          "response_time_ms": 120
        }
      }
    ]
  }'

You can send up to 100 events per request.

Field Reference

Field	Type	Required	Description
event_id	string	Yes	Unique identifier for the event. Used for idempotency (no duplicates).
customer_id	string	Yes	Unique identifier for the customer this event belongs to. For best results, use an ID that is consistent across all your systems, such as CRM, Billing, and support platforms.
event_code	string	Yes	The metric code this event should be counted towards (e.g., api_call).
event_type	string	Yes	credit or debit. Indicates if the event adds to or subtracts from the metric.
created_at	string	Yes	Timestamp in ISO 8601 format (e.g., 2025-03-25T12:00:00Z).
event_properties	object	No	Key-value pairs for custom properties (e.g., tokens, region). Used for aggregation, filtering, and grouping.

event_id

This field is required. It must be a unique string for each event. Quivly uses event_id to ensure idempotency—if you resend an event with the same event_id, it will not be ingested again.

customer_id

This field is required. It uniquely identifies the customer associated with the event. Use a consistent identifier for each customer across all events.

For best results, use an ID that is consistent across all your systems, such as CRM, Billing, and support platforms.

event_code

This field is required. It specifies which metric this event should be counted towards (e.g., api_call). The value must match the code of a metric you have defined in Quivly.

event_type

This field is required. It determines how the event impacts your metric. It accepts two values:

• credit: Adds to the metric (e.g., usage, accrual)
• debit: Subtracts from the metric (e.g., refunds, rollbacks, failed API calls, usage reductions)

created_at

This field is required. It must be in RFC 3339 format within ISO 8601 (e.g., 2025-03-25T12:00:00Z), and must be in UTC.

Timestamps will automatically be converted to your local timezone when viewed in the Quivly dashboard.

Incorrect or missing timestamps may cause events to be dropped or misattributed.

event_properties

This is an optional field. event_properties is a flexible object for storing custom data relevant to the event. Use it to:

• Track usage details (e.g., tokens, amount)
• Add context for grouping (e.g., region, instance_type)
• Enable filtering (e.g., status_code, environment)

Properties in event_properties can be used for aggregation (Sum, Average, etc.), grouping (Group By), and filtering in your metrics configuration.

Sending Events in Batch

• You can send up to 100 events per request in the events array.
• For high-volume ingestion, batch your events to reduce API calls and improve performance.

Event Processing Time

Events may take up to 15 minutes to appear in the Quivly events dashboard. If you don’t see your event after that, retry sending it with the same event_id.