Skip to main content

​
What are Dimensions?

Dimensions are categorical string values attached to events. They enable filtering and grouping across meters, limits, and analytics.
Use CaseDimensionExample Values
Model trackingmodel"gpt-4", "gpt-3.5-turbo"
Team allocationteam_id"engineering", "sales"
Feature usagefeature"chat", "search"
Environmentenvironment"prod", "staging"
Providerprovider"openai", "anthropic"

​
Adding Dimensions to Events

Include dimensions when recording events: 
limitry.events.record(
    customer_id="cust_123",
    event_type="llm.completion",
    values={"tokens": 500, "cost_cents": 25},
    dimensions={
        "model": "gpt-4",
        "provider": "openai",
        "feature": "chat",
        "team_id": "engineering",
        "environment": "prod"
    }
)

​
Filtering Meters by Dimension

Create meters that only aggregate events matching specific dimensions: 
# Only count GPT-4 tokens
gpt4_meter = client.meters.create(
    name="GPT-4 Tokens",
    event_type="llm.completion",
    aggregation="sum",
    value_key="tokens",
    dimension_filters={"model": "gpt-4"}
)

# Only count production usage
prod_meter = client.meters.create(
    name="Production Requests",
    event_type="llm.completion",
    aggregation="count",
    dimension_filters={"environment": "prod"}
)

​
Filtering Limits by Dimension

Apply limits to specific subsets of usage: 
# Limit GPT-4 usage per team
limit = client.limits.create(
    name="Engineering GPT-4 limit",
    meter_id=token_meter.id,
    limit_value=100000,
    period="month",
    customer_id="cust_123",
    dimension_filters={
        "model": "gpt-4",
        "team_id": "engineering"
    }
)
When checking limits, only events matching all specified dimensions count toward the limit.

​
Filtering Balances by Dimension

Allocate credit balances per team or user: 
# Per-team credit allocation
balance = client.balances.create(
    customer_id="cust_123",
    name="Engineering Credits",
    unit="cents",
    initial_balance=10000,
    dimension_filters={"team_id": "engineering"}
)

​
Usage Breakdown by Dimension

Query usage grouped by dimension values: 
breakdown = client.usage.breakdown(
    customer_id="cust_123",
    meter_id="mtr_tokens",
    group_by="model",
    period="month"
)

for item in breakdown.data:
    print(f"{item.dimension}: {item.value} tokens")
# Output:
# gpt-4: 250000 tokens
# gpt-3.5-turbo: 150000 tokens

​
Common Dimension Patterns

​
By AI Model

Track usage and costs across different models: 
dimensions={
    "model": "gpt-4",
    "provider": "openai"
}

​
By Team or User

Allocate usage within an organization: 
dimensions={
    "team_id": "engineering",
    "user_id": "alice"
}

​
By Feature

Understand which features drive usage: 
dimensions={
    "feature": "chat",
    "module": "customer-support"
}

​
By Environment

Separate production from development: 
dimensions={
    "environment": "prod",
    "region": "us-east-1"
}

​
Dimension Matching Rules

When filtering by dimensions:
  • All specified dimensions must match - If a limit has {"model": "gpt-4", "team_id": "eng"}, an event must have both dimensions with those exact values
  • Extra dimensions are ignored - An event with {"model": "gpt-4", "team_id": "eng", "user_id": "alice"} still matches
  • Missing dimensions don’t match - An event with only {"model": "gpt-4"} won’t match a filter requiring team_id

​
Best Practices

  1. Use consistent dimension names - Stick to snake_case (e.g., team_id not teamId)
  2. Keep values lowercase - Use "gpt-4" not "GPT-4" for easier filtering
  3. Don’t over-dimension - Only add dimensions you’ll actually filter or group by
  4. Use values, not dimensions, for numbers - Dimensions are for categorical data only