Skip to main content

​
What is an Event?

An event is a record of a single operation in your application. Events use a generic structure with values (numeric data) and dimensions (categorical data).
FieldDescriptionExample
customerIdWho made the request"cust_123"
eventTypeType of operation"llm.completion"
valuesNumeric measurements{"tokens": 500, "cost_cents": 25}
dimensionsCategorical attributes{"model": "gpt-4", "feature": "chat"}
timestampWhen it occurredAuto-set or custom

​
Recording Events

Use events.record after each operation: 
limitry.events.record(
    customer_id="cust_123",
    event_type="llm.completion",
    values={
        "tokens": 500,
        "cost_cents": 25,
        "latency_ms": 1200
    },
    dimensions={
        "model": "gpt-4",
        "provider": "openai",
        "feature": "chat"
    }
)

​
Values vs Dimensions

​
Values (Numeric)

Values are numbers that can be aggregated by meters: 
values={
    "tokens": 500,           # Can sum across events
    "cost_cents": 25,        # Can sum for billing
    "latency_ms": 1200,      # Can average or max
    "count": 1               # For counting resources
}
Use values for anything you want to:
  • Sum up (total tokens, total cost)
  • Find the max (peak usage)
  • Track over time (daily usage)

​
Dimensions (Categorical)

Dimensions are strings used for filtering and grouping: 
dimensions={
    "model": "gpt-4",        # Filter usage by model
    "provider": "openai",    # Group by provider
    "feature": "chat",       # Track feature usage
    "team": "engineering",   # Segment by team
    "environment": "prod"    # Separate prod/dev
}
Use dimensions for:
  • Filtering in meters (sum tokens where model = gpt-4)
  • Filtering in limits (limit only GPT-4 usage)
  • Breakdowns in analytics (usage by model)

​
Event Types

Use descriptive event types to categorize operations:
Event TypeUse Case
llm.completionChat/text completions
llm.embeddingText embedding generation
image.generationImage creation
agent.runAgent execution
feature.usageFeature access tracking
resource.createdResource creation (for counting)
resource.deletedResource deletion

​
Examples

​
LLM Completion

limitry.events.record(
    customer_id="cust_123",
    event_type="llm.completion",
    values={
        "input_tokens": 150,
        "output_tokens": 350,
        "total_tokens": 500,
        "cost_cents": 25
    },
    dimensions={
        "model": "gpt-4",
        "provider": "openai"
    }
)

​
Image Generation

limitry.events.record(
    customer_id="cust_123",
    event_type="image.generation",
    values={
        "images": 4,
        "cost_cents": 80
    },
    dimensions={
        "model": "dall-e-3",
        "size": "1024x1024",
        "quality": "hd"
    }
)

​
Resource Count (Gauge)

For tracking current resource counts, use latest aggregation in your meter: 
# When a resource is created
limitry.events.record(
    customer_id="cust_123",
    event_type="agent.count",
    values={"count": 5}  # Current total after creation
)

# When a resource is deleted
limitry.events.record(
    customer_id="cust_123",
    event_type="agent.count",
    values={"count": 4}  # Current total after deletion
)

​
List Events

Retrieve recorded events with filtering: 
# List all events
events = limitry.events.list()

for event in events.data:
    print(f"{event.id}: {event.customer_id} - {event.event_type}")
    print(f"  Values: {event.values}")
    print(f"  Dimensions: {event.dimensions}")

# Filter by customer
events = limitry.events.list(customer_id="cust_123")

# Filter by event type
events = limitry.events.list(event_type="llm.completion")

# Pagination
events = limitry.events.list(limit=50)
if events.has_more:
    next_page = limitry.events.list(cursor=events.next_cursor)

​
Batch Recording

Record multiple events efficiently: 
result = limitry.events.batch_ingest(
    events=[
        {
            "customer_id": "cust_123",
            "event_type": "llm.completion",
            "values": {"tokens": 500},
            "dimensions": {"model": "gpt-4"}
        },
        {
            "customer_id": "cust_456",
            "event_type": "llm.embedding",
            "values": {"tokens": 1000},
            "dimensions": {"model": "text-embedding-3-small"}
        }
    ]
)

print(f"Recorded {result.count} events")

​
How Events Flow to Meters

Events are the raw data. Meters aggregate them: See Meters to learn how to aggregate events into metrics.