Track Usage
Track consumption events for metered features with the Commet SDK.
Every metered feature has an event code. Your application sends events with that code, and Commet aggregates them for billing at the end of the period.
Usage event components
| Component | Description | Example |
|---|---|---|
| Feature | Event code of a metered feature | api_calls, storage_gb |
| Value | Quantity consumed | 1, 0.5, 100 |
| Customer | Who consumed it | customerId: "user_123" |
| Idempotency Key | Prevents duplicate events | "req_abc123" |
| Timestamp | When it happened (defaults to now) | "2026-01-15T10:00:00Z" |
Setting up event codes
When you create a metered feature in the dashboard, you define its event code. Go to Features, click Create Feature, select Metered, and enter the event code.
Event code conventions
| Good Event Codes | Bad Event Codes |
|---|---|
api_calls | feature1 |
storage_gb | metric |
emails_sent | usage |
compute_minutes | x |
Use snake_case. Be descriptive — this is what appears in code.
Track a single event
await commet.usage.track({
customerId: "user_123",
feature: "api_calls",
value: 1,
})Pass either a Commet ID (cus_xxx) or your external ID as customerId.
Track in batches
More efficient for high-volume tracking. Maximum 100 events per batch request.
await commet.usage.trackBatch({
events: [
{ customerId: "user_123", feature: "api_calls", value: 1 },
{ customerId: "user_456", feature: "api_calls", value: 3 },
{ customerId: "user_123", feature: "storage_gb", value: 0.5 },
],
})Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
feature | string | Yes | Event code of a metered feature. Only lowercase letters, numbers, and underscores (a-z0-9_) |
customerId | string | Yes | Commet customer ID (cus_xxx) or your external ID |
value | number | No | Quantity consumed. Must be >= 0. Defaults to 1 |
idempotencyKey | string | No | Prevents duplicate events |
timestamp | string | No | ISO 8601 datetime. Defaults to now |
properties | array | No | Key-value metadata for debugging |
Idempotency
Prevent duplicate charges by passing an idempotencyKey. Commet rejects events with a key that was already recorded for the same customer.
await commet.usage.track({
customerId: "user_123",
feature: "api_calls",
value: 1,
idempotencyKey: "req_abc123",
})Related
- AI Token Billing — Automatically track and charge for AI model tokens
- Configure Features — Create metered features and event codes
- Consumption Models — How usage is billed across metered, credits, and balance
How is this guide?