Skip to main content
Meters convert raw events into billable quantities. They filter events and apply aggregation functions (Count, Sum, Max, Last) to calculate usage per customer.
Meter creation interface showing event name, aggregation type, and filtering options

​
API Resources

​
Creating a Meter

1

Basic Information

​
Meter Name
string
required
Descriptive name (e.g., “API Requests”, “Token Usage”)
​
Event Name
string
required
Exact event name to match (case-sensitive). Examples: api.call, image.generated
2

Aggregation

​
Aggregation Type
string
required
Choose how events are aggregated:
  • Count: Total number of events (API calls, uploads)
  • Sum: Add numeric values (tokens, bytes)
  • Max: Highest value in period (peak users)
  • Last: Most recent value
​
Over Property
string
Metadata key to aggregate (required for all types except Count). Examples: tokens, bytes, duration_ms
​
Measurement Unit
string
required
Unit label for invoices. Examples: calls, tokens, GB, hours
3

Filtering (Optional)

Event filtering
Add conditions to filter which events are counted:
  • AND logic: All conditions must match
  • OR logic: Any condition can match
Comparators: equals, not equals, greater than, less than, containsEnable filtering, choose logic, add conditions with property key, comparator, and value.
4

Create

Review configuration and click Create Meter.

​
Viewing Analytics

Meter analytics
Your meter dashboard shows:
  • Overview: Total usage and usage chart
  • Events: Individual events received
  • Customers: Per-customer usage and charges

​
Billing in Credits Instead of Currency

By default, meters charge customers per-unit in dollars (or your configured currency). You can instead configure a meter to deduct from a credit balance - so usage consumes credits rather than generating a monetary charge.
Credit-based deduction requires a Credit Entitlement attached to the same product. Create your credit first, then link it to the meter.

​
When to Use Credit-Based Deduction

ScenarioStandard (currency)Credit-based
Simple per-unit pricing ($0.01/call)✅ Best fitUnnecessary overhead
Prepaid credit packs (buy 10K tokens, use over time)❌ Can’t express✅ Best fit
Bundled usage with subscriptions (Pro plan includes 100K calls)Possible via free threshold✅ Better - credits roll over, expire, show in portal
Multi-meter products sharing a credit pool❌ Each meter bills separately✅ All meters deduct from one balance

​
Configuring a Meter to Deduct Credits

1

Create a Credit Entitlement

First, create a credit in Products → Credits. Define the unit (e.g., “API Calls”, “Tokens”), precision, and lifecycle settings (expiry, rollover, overage).See the Credit-Based Billing guide for detailed instructions.
2

Create or Edit a Usage-Based Product

Go to your usage-based product and open the Meter configuration section.
3

Add a Meter

Click the + button to attach a meter. Configure the event name, aggregation type, and measurement unit as usual.
4

Enable 'Bill Usage in Credits'

Toggle Bill usage in Credits on the meter configuration. This reveals the credit settings:
Meter configuration with Bill usage in Credits toggle enabled
​
Credit Entitlement
string
required
Select which credit entitlement this meter should deduct from.
​
Meter units per credit
number
required
The number of usage units required to deduct 1 credit. For example:
  • 1 = each meter event deducts 1 credit
  • 100 = 100 meter events deduct 1 credit
  • 1000 = 1,000 API calls consume 1 credit
5

Set the Free Threshold

The Free Threshold still applies - events below this threshold don’t deduct credits.Example: With a free threshold of 1,000 and meter-units-per-credit of 1:
  • Customer uses 2,500 API calls
  • First 1,000 are free
  • Remaining 1,500 deduct 1,500 credits from their balance

​
How Credit Deduction Works

Once configured, the deduction pipeline runs automatically:
  1. Events arrive - Your application sends usage events via the Event Ingestion API
  2. Meter aggregates - Events are aggregated per your meter configuration (Count, Sum, Max, Last)
  3. Background worker processes - Every minute, a worker fetches new events since the last checkpoint
  4. Credits are deducted - Aggregated usage is converted to credits using the meter_units_per_credit rate and deducted using FIFO ordering (oldest grants consumed first)
  5. Overage tracked - If the balance hits zero and overage is enabled, usage continues and overage is handled according to the configured behavior (forgiven at reset, billed at next invoice, or carried forward as deficit)
Credit deduction runs asynchronously (every ~1 minute). There may be a brief delay between event ingestion and balance deduction. Design your application to handle this delay - don’t rely on real-time balance checks for access control on individual requests.

​
Multiple Meters, One Credit Pool

You can link multiple meters on the same product to the same credit entitlement. All meters deduct from one shared balance. Example: An AI platform with two meters:
  • text.generation - 1 credit per 1,000 tokens
  • image.generation - 10 credits per image
Both deduct from the same “AI Credits” pool. The customer sees a single unified balance in their portal.
Use different meter_units_per_credit rates across meters to express relative costs. Expensive operations (image generation) cost fewer meter units per credit than cheap ones (text completion).

List Customer Ledger

View the full credit deduction history for a customer.

Get Customer Balance

Check a customer’s current credit balance via API.

​
Troubleshooting

  • Event name must match exactly (case-sensitive)
  • Check meter filters aren’t excluding events
  • Verify customer IDs exist
  • Temporarily disable filters to test
  • Verify Over Property matches metadata key exactly
  • Use numbers, not strings: tokens: 150 not "150"
  • Include required properties in all events
  • Match case exactly
  • Use correct operators for data type
  • Ensure events include filtered properties
  • Check Events tab to count actual events received
  • Verify aggregation type (Count vs Sum)
  • Ensure values are numeric for Sum/Max

​
Next Steps

Send Events

Start sending usage events from your application to your meters.

View Blueprints

Use ready-made meter configurations for common use cases.