Defining pricing metrics

Pricing metrics define how to aggregate usage events over a service period that is billed to your customer.

Standard aggregation types

Most pricing metrics can be modeled using standard aggregation types.

• count - count the total number of usage events for a given event type.
  • Example: pricing by the number of API requests where you send a usage event for each request.
• sum - for a given event type and a field in that event, return the sum of the field over all the events.
  • Example: pricing by compute time, where your usage events have a field called duration_hours.
• max - for a given event type and a field in that event, return the maximum value of the field over all the events.
  • Example: pricing by number of concurrent database connections, where your usage events have a field called concurrent_connections.
• min - for a given event type and a field in that event, return the minimum value of the field over all the events.
• mean - for a given event type and a field in that event, return the mean value of the field over all the events.

Custom SQL aggregation types

You can also define pricing metrics using custom SQL. This can be useful for complex aggregation logic that isn’t supported by the standard aggregation types.

For instance, you price by total compute seconds but you track usage through heartbeat events every few seconds for each job execution.

Example heartbeat usage event:

{
    "timestamp": "2025-01-01T00:00:00Z",
    "subject_id": "<user_id>",
    "event_name": "job_execution_heartbeat",
    "data": {
        "job_runtime_seconds": "100.5", // total seconds running for the job execution
        "job_execution_id": "job_execution_123"
    },
    "idempotency_key": "<idempotency_key>"
}

Based on the above usage event, you can create a pricing metric with custom SQL aggregation to compute the max of the job_runtime_seconds field per job execution.

If you’re interested in using custom SQL aggregation, contact us at team@uselark.ai.

Dimensional pricing metrics

Dimensional pricing metrics allow you to bill for usage based with a price that varies by dimension(s).

For example, if you bill for AI inference based on the model used and the region where the model is hosted the dimensions would be model and region.

To create a dimensional pricing metric, you need to specify the dimensions and the aggregation type.

SDK

Create a dimensional pricing metric

pricing_metric = lark_client.pricing_metrics.create(
    name="Compute usage",
    event_name="compute_seconds",
    aggregation={"aggregation_type": "sum"},
    dimensions=[
       "region",
       "instance_type",
    ],
)

Dashboard

1. Go to the pricing metrics page and click “Create Pricing Metric”.
2. Fill in the form with the following values:
   • Name: Compute usage
   • Event Name: compute_seconds
   • Aggregation: sum
   • Dimensions (under “Advanced options”): region, instance_type
3. Click “Save”.

Then, for each usage event, specify the dimension values in the data field.

lark_client.usage_events.create(
    event_name="ai_inference",
    subject_id="<user_id>",
    timestamp=datetime.now(timezone.utc),
    idempotency_key="<idempotency_key>",
    data={
        "model": "gpt-5",
        "region": "us-east-1",
        "input_tokens": "100",
        "output_tokens": "50",
    },
)