What is a Meter?
A meter defines how raw events are aggregated into a single metric. Meters are the foundation of limits — they tell Limitry what to measure.
| Component | Description | Example |
|---|
| Field | Which value to aggregate | values.tokens, values.cost_cents |
| Aggregation | How to combine values | sum, count, max, latest |
| Event Filter | Optional event type and dimension filters | { eventType: "llm.completion", dimensions: { model: "gpt-4" } } |
Aggregation Types
| Type | Description | Use Case |
|---|
sum | Add up all values | Total tokens, total cost |
count | Count number of events | Number of requests |
max | Highest value seen | Peak concurrent users |
latest | Most recent value | Current resource count |
Creating Meters
from limitry import Limitry
client = Limitry()
# Sum of tokens across all completions
meter = client.meters.create(
name="Total Tokens",
aggregation="sum",
field="values.tokens",
event_filter={"event_type": "llm.completion"}
)
# Count of requests
meter = client.meters.create(
name="Request Count",
aggregation="count",
field="*",
event_filter={"event_type": "llm.completion"}
)
# Current agent count (using latest aggregation)
meter = client.meters.create(
name="Active Agents",
aggregation="latest",
field="values.count",
event_filter={"event_type": "agent.count"}
)
Event Filters
Filter which events are included in the meter:
# Only count GPT-4 tokens
meter = client.meters.create(
name="GPT-4 Tokens",
aggregation="sum",
field="values.tokens",
event_filter={
"event_type": "llm.completion",
"dimensions": {"model": "gpt-4"}
}
)
# Count premium feature usage
meter = client.meters.create(
name="Premium Features",
aggregation="count",
field="*",
event_filter={
"event_type": "feature.usage",
"dimensions": {"tier": "premium"}
}
)
Querying Meter Values
Get the current meter value for a customer:
# Query meter value for a customer
result = client.meters.query(
id="mtr_abc123",
customer_id="cust_123"
)
print(f"Meter: {result.meter_name}")
print(f"Value: {result.value}")
print(f"Aggregation: {result.aggregation}")
Meter + Limit Workflow
Meters and limits work together:
Example: Token Limit
# 1. Create a meter to sum tokens
token_meter = client.meters.create(
name="Total Tokens",
aggregation="sum",
field="values.tokens",
event_filter={"event_type": "llm.completion"}
)
# 2. Create a limit that uses this meter
daily_limit = client.limits.create(
name="Daily token limit",
meter_id=token_meter.id,
limit_value=100000,
period="day",
customer_id="cust_123"
)
# 3. Check before making requests
check = client.limits.check(customer_id="cust_123")
if check.allowed:
# Make LLM call...
# 4. Record the event
client.events.record(
customer_id="cust_123",
event_type="llm.completion",
values={"tokens": 500}
)
List Meters
meters = client.meters.list()
for meter in meters.data:
print(f"{meter.name} ({meter.id})")
print(f" {meter.aggregation}({meter.value_key}) for {meter.event_type}")
Update a Meter
meter = client.meters.update(
"mtr_abc123",
name="Updated meter name"
)
Delete a Meter
result = client.meters.delete("mtr_abc123")
Deleting a meter will also delete any limits that reference it.
