Usage tracking

Lark supports sending usage events at a rate of up to 1,000,000 (1M) events per second. If you require higher throughput, please contact us at team@uselark.ai.

Sending usage events

To report usage events you can call the usage events API.

lark_client.usage_events.create(
    idempotency_key="your-unique-idempotency-key",
    timestamp=datetime.now(timezone.utc),
    event_name="ai_chat_request",
    subject_id=subject.id,
    data={"value": "1"},
)

Idempotency key: This is a unique identifier for the usage event to ensure the event is only processed once. It can be some identifier in your system (for example a message id) that is 1:1 with a usage event.

Event name: The event name of the associated pricing metric(s).

Subject ID: This is the ID of the subject (customer) for which the usage event is being reported.

Data: This is the data for the usage event. It should include the aggregation field of the associated pricing metric(s). Optionally, it can include extra key-value pairs that may be used for future pricing metrics.

Querying usage data

To view aggregated usage for a subject over a given period, fetch the pricing metric summary.

summary = lark_client.pricing_metrics.create_summary(
    pricing_metric_id=pricing_metric.id,
    subject_id=subject.id,
    period={
        "start": datetime.now(timezone.utc) - timedelta(days=30),
        "end": datetime.now(timezone.utc),
    },
)
print(summary)
'''
{
  "id": "pmtr_sum_fjxpDpdaPbvA7acpWzD2U3Ax",
  "pricing_metric_id": "pmtr_HHCFQfe2rKd4Oa1hzX1gDwg1",
  "subject_id": "subj_wv8qXxM8q0FOQvrKcmikissE",
  "period": {
    "inclusive_start": true,
    "inclusive_end": false,
    "start": "2025-10-01T00:00:00Z",
    "end": "2025-11-01T00:00:00Z"
  },
  "value": "27.5"
}
'''