Skip to main content

​
Overview

Meters define how API requests are billed to your customers. Each meter specifies:
  • Rate type - Fixed fee per unit or percentage of base cost
  • Token basis - Bill on input+output tokens or output only
  • Tiers - Volume-based pricing tiers
  • Cost allocation - Who pays for base costs and service charges
Meters are created and configured in the Lava dashboard. Use these SDK methods to retrieve meter details programmatically.

​
Methods

​
list()

List all meters for your merchant account. Signature 
list(params?: {
  cursor?: string;
  limit?: number;
}): Promise<ListResponse<RestMeter>>
Parameters
NameTypeRequiredDescription
cursorstringNoPagination cursor from previous response
limitnumberNoNumber of results to return (max 100, default 20)
Returns 
{
  data: Array<{
    meter_id: string;
    meter_secret: string;
    name: string;
    rate_type: 'fixed' | 'percentage';
    token_basis: 'input+output' | 'output';
    base_cost_payer: 'merchant' | 'wallet';
    service_charge_payer: 'merchant' | 'wallet';
    tiers: Array<{
      start: number;
      rate: string;
      type: 'tokens_1m' | 'characters_1m' | 'minutes' | 'requests';
    }>;
    created_at: string;
  }>;
  has_more: boolean;
  next_cursor: string | null;
}
Example 
const { data: meters } = await lava.meters.list();

for (const meter of meters) {
  console.log(`${meter.name} (${meter.meter_id})`);
  console.log(`  Rate type: ${meter.rate_type}`);
  console.log(`  Token basis: ${meter.token_basis}`);
  console.log(`  Tiers: ${meter.tiers.length}`);
}

​
retrieve()

Retrieve a specific meter by ID. Signature 
retrieve(id: string): Promise<RestMeter>
Parameters
NameTypeRequiredDescription
idstringYesMeter ID
Returns Single RestMeter object. Example 
const meter = await lava.meters.retrieve('meter_abc123');

console.log(`Meter: ${meter.name}`);
console.log(`Rate type: ${meter.rate_type}`);
console.log(`Base cost payer: ${meter.base_cost_payer}`);

// Display tier pricing
for (const tier of meter.tiers) {
  console.log(`  ${tier.start}+ ${tier.type}: ${tier.rate}`);
}

​
Type Reference

​
RestMeter

type RestMeter = {
  meter_id: string;
  meter_secret: string;
  name: string;
  rate_type: 'fixed' | 'percentage';
  token_basis: 'input+output' | 'output';
  base_cost_payer: 'merchant' | 'wallet';
  service_charge_payer: 'merchant' | 'wallet';
  tiers: RestMeterTier[];
  created_at: string;
};

​
RestMeterTier

type RestMeterTier = {
  start: number;           // Volume threshold (e.g., 0, 1000000)
  rate: string;            // Rate as decimal string (e.g., "0.50")
  type: 'tokens_1m' | 'characters_1m' | 'minutes' | 'requests';
};

​
Rate Types

​
Fixed (rate_type: 'fixed')

Charges a fixed fee per unit (token, character, minute, or request): 
Fee = rate × units
Example: $0.50 per 1M tokens means 500,000 tokens costs $0.25

​
Percentage (rate_type: 'percentage')

Charges a percentage of the base API cost: 
Fee = rate × base_cost
Example: 10% rate on a $1.00 API call costs $0.10

​
Token Basis

​
Input + Output (token_basis: 'input+output')

Bills based on total tokens (input + output). Most common for chat completions.

​
Output Only (token_basis: 'output')

Bills based on output tokens only. Useful for generation-heavy use cases.

​
Cost Payers

​
Base Cost Payer (base_cost_payer)

Who pays for the underlying API provider costs:
  • 'merchant' - You absorb provider costs
  • 'wallet' - Customer pays provider costs from their balance

​
Service Charge Payer (service_charge_payer)

Who pays Lava’s service charge:
  • 'merchant' - You absorb service charges
  • 'wallet' - Customer pays service charges from their balance