Skip to main content

​
Why Pricing Simulation Matters

Traditional SaaS pricing breaks down fast for AI agents because usage varies wildly. Some customers generate $50 in costs, others $700. A flat fee means you’re either:
  • Undercharging power users — leaving money on the table
  • Overcharging light users — driving them away
  • Going negative on high-usage customers — literally paying them to use your product
The Pricing Simulator lets you model, test, and validate usage-based pricing before going live. Play with different pricing structures, see projected revenue and margins, and find the sweet spot where you make money without surprising your customers.

​
How It Works

The Pricing Simulator is a dev-first tool that bridges your telemetry data with billing logic. Here’s the flow: 
Your AI Agent Usage           Pricing Simulator               Revenue Prediction
─────────────────   →   ──────────────────────   →    ─────────────────
• 50,000 sessions            1. Select telemetry source     • Revenue: $1,450
• 5M spans                   2. Choose pricing type         • Costs: $1,255
• 500M tokens                3. Set multipliers/tiers       • Margin: 13.4%
• 5GB logs                   4. Apply filters               • Per-session: $0.029
                            5. Run simulation
You can test pricing models against:
  • Historical data (last month’s actual usage)
  • Hypothetical scenarios (2x growth, new feature launch)
  • Individual customers (understand per-customer economics)
  • Different pricing models side-by-side (compare 3 pricing strategies instantly)

​
Pricing Models You Can Build

The simulator supports the most common usage-based pricing patterns AI companies use:

Tiered Subscription

Free tier + volume discounts. Example: First 1M spans free, then 0.00005perspanupto10M,then0.00005 per span up to 10M, then 0.00003 thereafter.

Pay-As-You-Go

Linear or tiered per-unit pricing. Example: 0.01persession,or0.01 per session, or 0.002 per 1k tokens.

Subscription + Overage

Base monthly fee + usage charges beyond included amount. Example: 500/monthincludes1Mspans,then500/month includes 1M spans, then 0.00005 per additional span.

Hybrid Model

Combine multiple pricing rules. Example: Base fee + per-session charge + per-token overage fee.
Thes pricing simulator enables you to design flexible pricing models by mapping telemetry data to revenue while running “what-if” scenarios against historical usage to project growth. Integrated margin analysis provides real-time visibility into COGS and unit profitability, ensuring your pricing strategy remains sustainable. Finally, “Shadow Mode” allows you to safely test these models and compare revenue impacts before a full rollout.

​
Quick Start Example

Here’s how a customer support agent company uses the simulator: Current problem: Flat $500/month, losing money on power users Step 1: Import last month’s usage 
{
  "sessions": 50000,
  "llm_tokens": 500000000,
  "llm_cost": 1000.00
}
Step 2: Build pricing model in UI or SDK 
const model = {
  name: "Pay-per-resolution model",
  rules: [
    {
      displayName: "Per Session",
      telemetrySource: "session",
      pricingType: "tiered",
      tiers: [
        { upto: 10000, unitPrice: 0.00 },       // First 10k free
        { upto: 50000, unitPrice: 0.012 },      // Next 40k at $0.012
        { upto: "unlimited", unitPrice: 0.008 } // Beyond 50k at $0.008
      ]
    }
  ],
  platformFees: { baseMonthlyFee: 200.00 }
}
Step 3: Run simulation 
{
  "revenue": 800.00,
  "costs": 1000.00,
  "margin": -25%,
  "recommendation": "Increase base fee or add token-based pricing"
}
Step 4: Adjust and re-test 
// Add token-based pricing to improve margins
rules: [
  { /* session pricing */ },
  {
    displayName: "High Token Usage Overage",
    telemetrySource: "raw",
    aggregationField: "usage_total_tokens",
    pricingType: "threshold",
    threshold: 400000000,  // Free up to 400M tokens
    overageRate: 0.000003  // $0.003 per 1k tokens beyond threshold
  }
]
New simulation: 
{
  "revenue": 1100.00,
  "costs": 1000.00,
  "margin": 9.1%,
  "status": "healthy"
}
Now you have a pricing model that preserves margins while scaling with usage.

​
Common Use Cases

​
1. Switching from Flat to Usage-Based Pricing

Scenario: You charge $500/month but margins are inconsistent. Solution:
  1. Run simulations on last 3 months of customer data
  2. Identify customers with negative margins
  3. Design tiered pricing that protects margins on high-usage customers
  4. Test in shadow mode with existing customers
  5. Roll out with grandfather pricing for early customers
Result: Predictable 15-20% margins across all customers.

​
2. Launching a New Feature with Separate Pricing

Scenario: Adding document analysis feature—should it be included or priced separately? Solution:
  1. Estimate usage based on beta testing data
  2. Create two pricing models: “included” vs. “separate add-on”
  3. Run simulations comparing projected revenue and churn risk
  4. Use filters to charge only customers using the feature
Result: Data-driven decision on feature pricing strategy.

​
3. Preventing Margin Erosion from Power Users

Scenario: Top 10% of customers consume 80% of resources but pay same as everyone. Solution:
  1. Run per-customer margin analysis
  2. Identify customers with less than 5% margins
  3. Design threshold-based pricing: included usage + overage fee
  4. Test impact on revenue and projected churn
  5. Communicate transparently with affected customers
Result: Healthy margins without losing valuable customers.

​
4. Validating Pricing Before Launch

Scenario: Pre-launch startup needs to price before first customer. Solution:
  1. Use synthetic usage data based on beta testing
  2. Build 3-5 pricing model variants
  3. Run what-if scenarios (low/medium/high usage)
  4. Calculate break-even points and target margins
  5. Choose model that balances growth and profitability
Result: Launch with confidence, avoid expensive pricing mistakes.

​
Integration with Billing

Once you’ve designed and validated your pricing model in the simulator, connect it to your billing system:
1

Save Your Pricing Model

Activate the pricing model via API or dashboard. This makes it available for production billing.
2

Configure Billing Webhooks

Set up webhooks to trigger billing events: billing.period_end, billing.threshold_reached, or manual export.
3

Map Customer Metadata

Ensure telemetry data includes customer_id so usage is attributed correctly.
4

Enable Shadow Mode (Optional)

Run the pricing model in shadow mode to generate reports without actual billing, perfect for validation.
5

Go Live

Switch from shadow mode to production. Webhooks automatically send billing data to Stripe, your internal system, or wherever you need it.
Pro tip: Always test new pricing models in shadow mode first. You’ll see exactly what customers would be charged before making it real.

​
Pricing Simulator API Reference

​
Overview

This document defines the API specification for a pricing simulator that enables users to build, manage, and test pricing models that convert usage records into bills. The API is designed to be SDK-compatible and follows REST conventions. Base URL: https://api.{domain}/v1

​
Authentication

All API requests require authentication via Bearer token in the Authorization header: 
Authorization: Bearer <api_key>

​
1. Pricing Models API

​
Data Model

interface PricingModel {
  model_id: string;                    // Unique identifier (auto-generated or user-provided)
  version: string;                     // Semantic version (e.g., "1.2.0")
  name: string;                        // Human-readable name
  description?: string;                // Optional description
  currency: string;                    // ISO 4217 currency code (e.g., "USD")
  status: "draft" | "active" | "archived";
  rules: PricingRule[];
  platform_fees?: PlatformFees;
  metadata?: Record<string, any>;      // Custom key-value pairs
  created_at: string;                  // ISO 8601 timestamp
  updated_at: string;                  // ISO 8601 timestamp
  created_by: string;                  // User/API key identifier
}

interface PricingRule {
  rule_id: string;                     // Unique within the model
  display_name: string;
  telemetry_source: "session" | "trace" | "span" | "raw";
  aggregation_method: "COUNT" | "SUM" | "AVG" | "MAX" | "MIN";
  aggregation_field?: string;          // Required when aggregation_method is not COUNT
  pricing_type: "tiered" | "flat_multiplier" | "threshold" | "flat_rate";
  
  // For tiered pricing
  tiers?: Tier[];
  
  // For flat_multiplier pricing
  multiplier?: number;
  per_unit_count?: number;
  
  // For threshold pricing
  threshold?: number;
  overage_rate?: number;
  
  // For flat_rate pricing
  flat_amount?: number;
  
  // Optional filters
  filters?: RuleFilter[];
}

interface Tier {
  upto: number | "unlimited";
  unit_price: number;
  flat_fee?: number;                   // Optional flat fee for this tier
}

interface RuleFilter {
  field: string;
  operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "contains";
  value: any;
}

interface PlatformFees {
  base_monthly_fee?: number;
  support_tier?: string;
  additional_fees?: AdditionalFee[];
}

interface AdditionalFee {
  name: string;
  amount: number;
  frequency: "monthly" | "annually" | "one_time";
}

​
1.1 List Pricing Models

Retrieve a paginated list of pricing models. Endpoint: GET /pricing-models Query Parameters:
ParameterTypeDefaultDescription
limitinteger20Number of results per page (1-100)
cursorstring-Pagination cursor from previous response
statusstring-Filter by status: draft, active, archived
searchstring-Search by name or description
sort_bystringcreated_atSort field: created_at, updated_at, name
sort_orderstringdescSort order: asc, desc
Request: 
GET /v1/pricing-models?limit=10&status=active
Response: 200 OK 
{
  "data": [
    {
      "model_id": "plan_ent_premium_001",
      "version": "1.2.0",
      "name": "Enterprise Usage-Based Plan",
      "description": "Tiered pricing based on spans and raw event ingestion",
      "currency": "USD",
      "status": "active",
      "rules_count": 4,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T14:45:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6InBsYW5fMDAxIiwidHMiOjE3MDU0MjAwMDB9",
    "total_count": 45
  }
}

​
1.2 Get Pricing Model

Retrieve a single pricing model by ID. Endpoint: GET /pricing-models/{model_id} Path Parameters:
ParameterTypeDescription
model_idstringThe pricing model identifier
Query Parameters:
ParameterTypeDefaultDescription
versionstringlatestSpecific version to retrieve
include_historybooleanfalseInclude version history
Request: 
GET /v1/pricing-models/plan_ent_premium_001?include_history=true
Response: 200 OK 
{
  "data": {
    "model_id": "plan_ent_premium_001",
    "version": "1.2.0",
    "name": "Enterprise Usage-Based Plan",
    "description": "Tiered pricing based on spans and raw event ingestion",
    "currency": "USD",
    "status": "active",
    "rules": [
      {
        "rule_id": "rule_spans_001",
        "display_name": "Distributed Tracing Spans",
        "telemetry_source": "span",
        "aggregation_method": "COUNT",
        "pricing_type": "tiered",
        "tiers": [
          { "upto": 1000000, "unit_price": 0.00 },
          { "upto": 10000000, "unit_price": 0.00005 },
          { "upto": "unlimited", "unit_price": 0.00003 }
        ]
      },
      {
        "rule_id": "rule_raw_001",
        "display_name": "Raw Logs Ingestion",
        "telemetry_source": "raw",
        "aggregation_method": "SUM",
        "aggregation_field": "payload_size_bytes",
        "pricing_type": "flat_multiplier",
        "multiplier": 0.15,
        "per_unit_count": 1073741824
      },
      {
        "rule_id": "rule_threshold_001",
        "display_name": "Usage Threshold",
        "telemetry_source": "raw",
        "aggregation_method": "SUM",
        "aggregation_field": "usage_total_tokens",
        "pricing_type": "threshold",
        "threshold": 1024000000
      },
      {
        "rule_id": "rule_session_001",
        "display_name": "User Sessions",
        "telemetry_source": "session",
        "aggregation_method": "COUNT",
        "pricing_type": "flat_multiplier",
        "multiplier": 0.01,
        "per_unit_count": 1
      }
    ],
    "platform_fees": {
      "base_monthly_fee": 500.00,
      "support_tier": "premium_24_7"
    },
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-02-20T14:45:00Z",
    "created_by": "user_abc123"
  },
  "version_history": [
    { "version": "1.2.0", "created_at": "2024-02-20T14:45:00Z", "change_summary": "Added threshold rule" },
    { "version": "1.1.0", "created_at": "2024-02-01T09:00:00Z", "change_summary": "Updated tier pricing" },
    { "version": "1.0.0", "created_at": "2024-01-15T10:30:00Z", "change_summary": "Initial version" }
  ]
}

​
1.3 Create Pricing Model

Create a new pricing model. Endpoint: POST /pricing-models Request Body: 
{
  "model_id": "plan_ent_premium_001",      // Optional - auto-generated if not provided
  "version": "1.0.0",                       // Optional - defaults to "1.0.0"
  "name": "Enterprise Usage-Based Plan",
  "description": "Tiered pricing based on spans and raw event ingestion",
  "currency": "USD",
  "status": "draft",                        // Optional - defaults to "draft"
  "rules": [
    {
      "rule_id": "rule_spans_001",          // Optional - auto-generated if not provided
      "display_name": "Distributed Tracing Spans",
      "telemetry_source": "span",
      "aggregation_method": "COUNT",
      "pricing_type": "tiered",
      "tiers": [
        { "upto": 1000000, "unit_price": 0.00 },
        { "upto": 10000000, "unit_price": 0.00005 },
        { "upto": "unlimited", "unit_price": 0.00003 }
      ]
    }
  ],
  "platform_fees": {
    "base_monthly_fee": 500.00,
    "support_tier": "premium_24_7"
  },
  "metadata": {
    "internal_code": "ENT-001",
    "department": "sales"
  }
}
Response: 201 Created 
{
  "data": {
    "model_id": "plan_ent_premium_001",
    "version": "1.0.0",
    "name": "Enterprise Usage-Based Plan",
    "status": "draft",
    "created_at": "2024-03-01T10:00:00Z",
    "updated_at": "2024-03-01T10:00:00Z"
  }
}
Validation Rules:
  • name is required and must be 1-255 characters
  • currency must be a valid ISO 4217 code
  • rules array must contain at least one rule
  • Each rule must have valid telemetry_source and pricing_type combinations
  • Tiered pricing must have at least one tier with the last tier having upto: "unlimited"
  • multiplier and per_unit_count are required for flat_multiplier pricing type

​
1.4 Update Pricing Model

Update an existing pricing model. This creates a new version. Endpoint: PUT /pricing-models/{model_id} Path Parameters:
ParameterTypeDescription
model_idstringThe pricing model identifier
Query Parameters:
ParameterTypeDefaultDescription
version_bumpstringminorVersion increment: major, minor, patch
Request Body: 
{
  "name": "Enterprise Usage-Based Plan v2",
  "description": "Updated tiered pricing",
  "rules": [
    {
      "rule_id": "rule_spans_001",
      "display_name": "Distributed Tracing Spans",
      "telemetry_source": "span",
      "aggregation_method": "COUNT",
      "pricing_type": "tiered",
      "tiers": [
        { "upto": 2000000, "unit_price": 0.00 },
        { "upto": 20000000, "unit_price": 0.00004 },
        { "upto": "unlimited", "unit_price": 0.000025 }
      ]
    }
  ],
  "change_summary": "Increased free tier and adjusted pricing"
}
Response: 200 OK 
{
  "data": {
    "model_id": "plan_ent_premium_001",
    "version": "1.3.0",
    "previous_version": "1.2.0",
    "name": "Enterprise Usage-Based Plan v2",
    "status": "draft",
    "updated_at": "2024-03-01T12:00:00Z"
  }
}

​
1.5 Partial Update (Patch) Pricing Model

Update specific fields without replacing the entire model. Endpoint: PATCH /pricing-models/{model_id} Request Body: 
{
  "status": "active",
  "platform_fees": {
    "base_monthly_fee": 600.00
  }
}
Response: 200 OK

​
1.6 Delete Pricing Model

Delete a pricing model (soft delete - moves to archived status). Endpoint: DELETE /pricing-models/{model_id} Query Parameters:
ParameterTypeDefaultDescription
hard_deletebooleanfalsePermanently delete (requires admin)
versionstringallSpecific version to delete, or “all”
Response: 200 OK 
{
  "data": {
    "model_id": "plan_ent_premium_001",
    "status": "archived",
    "deleted_at": "2024-03-01T15:00:00Z"
  }
}

​
1.7 Clone Pricing Model

Create a copy of an existing pricing model. Endpoint: POST /pricing-models/{model_id}/clone Request Body: 
{
  "new_model_id": "plan_ent_premium_002",   // Optional
  "new_name": "Enterprise Plan - APAC",
  "include_metadata": true
}
Response: 201 Created

​
1.8 Validate Pricing Model

Validate a pricing model configuration without saving. Endpoint: POST /pricing-models/validate Request Body: Same as Create Pricing Model Response: 200 OK 
{
  "valid": true,
  "warnings": [
    {
      "rule_id": "rule_spans_001",
      "message": "Large gap between tier 1 and tier 2 thresholds"
    }
  ],
  "errors": []
}
Response: 400 Bad Request (if invalid) 
{
  "valid": false,
  "warnings": [],
  "errors": [
    {
      "field": "rules[0].tiers",
      "code": "INVALID_TIER_ORDER",
      "message": "Tiers must be in ascending order"
    }
  ]
}

​
2. Pricing Simulation API

​
Data Model

interface SimulationRequest {
  model_id?: string;                   // Use existing model OR
  pricing_model?: PricingModel;        // Provide inline model for testing
  
  usage_data: UsageDataInput;
  
  simulation_options?: SimulationOptions;
}

interface UsageDataInput {
  // Option 1: Time range query (pulls from your telemetry store)
  time_range?: {
    start: string;                     // ISO 8601
    end: string;                       // ISO 8601
  };
  customer_id?: string;
  
  // Option 2: Direct usage records
  records?: UsageRecord[];
  
  // Option 3: Aggregated summaries
  aggregated?: AggregatedUsage;
}

interface UsageRecord {
  telemetry_source: "session" | "trace" | "span" | "raw";
  timestamp: string;
  count?: number;                      // For pre-aggregated data
  properties: Record<string, any>;     // e.g., { payload_size_bytes: 1024 }
}

interface AggregatedUsage {
  sessions?: { count: number };
  traces?: { count: number };
  spans?: { count: number };
  raw?: {
    count: number;
    payload_size_bytes_total?: number;
    usage_total_tokens?: number;
  };
}

interface SimulationOptions {
  include_breakdown: boolean;          // Detailed per-rule breakdown
  include_what_if: boolean;            // Include cost at different usage levels
  compare_models?: string[];           // Compare with other model_ids
  currency_conversion?: string;        // Convert result to different currency
  apply_discounts?: Discount[];        // Apply promotional discounts
}

interface Discount {
  type: "percentage" | "fixed";
  value: number;
  applies_to?: string[];               // Rule IDs, or all if empty
}

interface SimulationResult {
  simulation_id: string;
  model_id: string;
  model_version: string;
  
  summary: {
    total_amount: number;
    currency: string;
    period: { start: string; end: string };
    
    subtotals: {
      rules_total: number;
      platform_fees_total: number;
      discounts_total: number;
    };
  };
  
  breakdown?: RuleBreakdown[];
  what_if?: WhatIfAnalysis[];
  comparison?: ModelComparison[];
  
  usage_summary: {
    sessions: number;
    traces: number;
    spans: number;
    raw_events: number;
    raw_bytes: number;
  };
  
  computed_at: string;
}

interface RuleBreakdown {
  rule_id: string;
  display_name: string;
  
  usage: {
    raw_value: number;
    unit: string;
    aggregated_value: number;
  };
  
  calculation: {
    pricing_type: string;
    applied_tiers?: AppliedTier[];
    multiplier_calculation?: string;   // e.g., "150000 units × $0.01 / 1 = $1500.00"
  };
  
  amount: number;
}

interface AppliedTier {
  tier_index: number;
  range: { from: number; to: number };
  units_in_tier: number;
  unit_price: number;
  tier_amount: number;
}

interface WhatIfAnalysis {
  scenario: string;                    // e.g., "2x current usage"
  multiplier: number;
  projected_total: number;
  difference: number;
  percentage_change: number;
}

interface ModelComparison {
  model_id: string;
  model_name: string;
  total_amount: number;
  difference_from_primary: number;
  percentage_difference: number;
}

​
2.1 Run Simulation

Execute a pricing simulation. Endpoint: POST /pricing-models/simulate Request Body: 
{
  "model_id": "plan_ent_premium_001",
  "usage_data": {
    "aggregated": {
      "sessions": 50000,
      "traces": 200000,
      "spans": 5000000,
      "raw": {
        "count": 1000000,
        "payload_size_bytes_total": 5368709120,
        "usage_total_tokens": 500000000
      }
    }
  },
  "simulation_options": {
    "include_breakdown": true,
    "include_what_if": true
  }
}
Response: 200 OK 
{
  "data": {
    "simulation_id": "sim_abc123",
    "model_id": "plan_ent_premium_001",
    "model_version": "1.2.0",
    
    "summary": {
      "total_amount": 1450.00,
      "currency": "USD",
      "period": {
        "start": "2024-03-01T00:00:00Z",
        "end": "2024-03-31T23:59:59Z"
      },
      "subtotals": {
        "rules_total": 950.00,
        "platform_fees_total": 500.00,
        "discounts_total": 0.00
      }
    },
    
    "breakdown": [
      {
        "rule_id": "rule_spans_001",
        "display_name": "Distributed Tracing Spans",
        "usage": {
          "raw_value": 5000000,
          "unit": "spans",
          "aggregated_value": 5000000
        },
        "calculation": {
          "pricing_type": "tiered",
          "applied_tiers": [
            {
              "tier_index": 0,
              "range": { "from": 0, "to": 1000000 },
              "units_in_tier": 1000000,
              "unit_price": 0.00,
              "tier_amount": 0.00
            },
            {
              "tier_index": 1,
              "range": { "from": 1000001, "to": 5000000 },
              "units_in_tier": 4000000,
              "unit_price": 0.00005,
              "tier_amount": 200.00
            }
          ]
        },
        "amount": 200.00
      },
      {
        "rule_id": "rule_raw_001",
        "display_name": "Raw Logs Ingestion",
        "usage": {
          "raw_value": 5368709120,
          "unit": "bytes",
          "aggregated_value": 5
        },
        "calculation": {
          "pricing_type": "flat_multiplier",
          "multiplier_calculation": "5 GB × $0.15 = $0.75"
        },
        "amount": 0.75
      },
      {
        "rule_id": "rule_session_001",
        "display_name": "User Sessions",
        "usage": {
          "raw_value": 50000,
          "unit": "sessions",
          "aggregated_value": 50000
        },
        "calculation": {
          "pricing_type": "flat_multiplier",
          "multiplier_calculation": "50000 sessions × $0.01 / 1 = $500.00"
        },
        "amount": 500.00
      }
    ],
    
    "what_if": [
      {
        "scenario": "50% of current usage",
        "multiplier": 0.5,
        "projected_total": 975.00,
        "difference": -475.00,
        "percentage_change": -32.76
      },
      {
        "scenario": "2x current usage",
        "multiplier": 2.0,
        "projected_total": 2400.00,
        "difference": 950.00,
        "percentage_change": 65.52
      },
      {
        "scenario": "5x current usage",
        "multiplier": 5.0,
        "projected_total": 5250.00,
        "difference": 3800.00,
        "percentage_change": 262.07
      }
    ],
    
    "usage_summary": {
      "sessions": 50000,
      "traces": 200000,
      "spans": 5000000,
      "raw_events": 1000000,
      "raw_bytes": 5368709120
    },
    
    "computed_at": "2024-03-01T10:00:00Z"
  }
}

​
2.2 Simulate with Inline Model

Test a pricing model without saving it first. Endpoint: POST /pricing-models/simulate Request Body: 
{
  "pricing_model": {
    "name": "Test Model",
    "currency": "USD",
    "rules": [
      {
        "display_name": "Spans",
        "telemetry_source": "span",
        "aggregation_method": "COUNT",
        "pricing_type": "flat_multiplier",
        "multiplier": 0.0001,
        "per_unit_count": 1
      }
    ]
  },
  "usage_data": {
    "aggregated": {
      "spans": 1000000
    }
  }
}

​
2.3 Compare Models

Compare pricing across multiple models. Endpoint: POST /pricing-models/simulate/compare Request Body: 
{
  "model_ids": [
    "plan_starter_001",
    "plan_pro_001",
    "plan_ent_premium_001"
  ],
  "usage_data": {
    "aggregated": {
      "sessions": 50000,
      "spans": 5000000,
      "raw": {
        "payload_size_bytes_total": 5368709120
      }
    }
  }
}
Response: 200 OK 
{
  "data": {
    "comparison_id": "cmp_xyz789",
    "usage_summary": {
      "sessions": 50000,
      "spans": 5000000,
      "raw_bytes": 5368709120
    },
    "results": [
      {
        "model_id": "plan_starter_001",
        "model_name": "Starter Plan",
        "total_amount": 2500.00,
        "currency": "USD",
        "rank": 3,
        "notes": ["No free tier"]
      },
      {
        "model_id": "plan_pro_001",
        "model_name": "Professional Plan",
        "total_amount": 1800.00,
        "currency": "USD",
        "rank": 2,
        "notes": ["Includes 1M free spans"]
      },
      {
        "model_id": "plan_ent_premium_001",
        "model_name": "Enterprise Usage-Based Plan",
        "total_amount": 1450.00,
        "currency": "USD",
        "rank": 1,
        "recommended": true,
        "notes": ["Best value for this usage level", "Includes premium support"]
      }
    ],
    "computed_at": "2024-03-01T10:00:00Z"
  }
}

​
2.4 Batch Simulation

Run simulations for multiple customers/periods. Endpoint: POST /pricing-models/simulate/batch Request Body: 
{
  "model_id": "plan_ent_premium_001",
  "simulations": [
    {
      "reference_id": "customer_001_jan",
      "customer_id": "cust_001",
      "time_range": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      }
    },
    {
      "reference_id": "customer_001_feb",
      "customer_id": "cust_001",
      "time_range": {
        "start": "2024-02-01T00:00:00Z",
        "end": "2024-02-29T23:59:59Z"
      }
    },
    {
      "reference_id": "customer_002_jan",
      "customer_id": "cust_002",
      "time_range": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      }
    }
  ]
}
Response: 202 Accepted (for async processing) 
{
  "data": {
    "batch_id": "batch_abc123",
    "status": "processing",
    "total_simulations": 3,
    "completed": 0,
    "status_url": "/v1/pricing-models/simulate/batch/batch_abc123"
  }
}

​
2.5 Get Batch Status

Endpoint: GET /pricing-models/simulate/batch/{batch_id} Response: 200 OK 
{
  "data": {
    "batch_id": "batch_abc123",
    "status": "completed",
    "total_simulations": 3,
    "completed": 3,
    "failed": 0,
    "results": [
      {
        "reference_id": "customer_001_jan",
        "status": "success",
        "total_amount": 1450.00,
        "currency": "USD"
      },
      {
        "reference_id": "customer_001_feb",
        "status": "success",
        "total_amount": 1680.00,
        "currency": "USD"
      },
      {
        "reference_id": "customer_002_jan",
        "status": "success",
        "total_amount": 890.00,
        "currency": "USD"
      }
    ]
  }
}

​
2.6 Margin Analysis

Analyze margins based on costs. Endpoint: POST /pricing-models/simulate/margin Request Body: 
{
  "model_id": "plan_ent_premium_001",
  "usage_data": {
    "aggregated": {
      "sessions": 50000,
      "spans": 5000000,
      "raw": {
        "payload_size_bytes_total": 5368709120,
        "usage_total_tokens": 500000000
      }
    }
  },
  "cost_inputs": {
    "llm_costs": {
      "total_tokens": 500000000,
      "cost_per_1k_tokens": 0.002
    },
    "infrastructure_costs": {
      "storage_gb": 5,
      "cost_per_gb": 0.10,
      "compute_hours": 100,
      "cost_per_hour": 0.05
    },
    "fixed_costs": {
      "support": 200.00,
      "overhead": 50.00
    }
  }
}
Response: 200 OK 
{
  "data": {
    "simulation_id": "sim_margin_001",
    "model_id": "plan_ent_premium_001",
    
    "revenue": {
      "total": 1450.00,
      "currency": "USD"
    },
    
    "costs": {
      "llm_costs": 1000.00,
      "infrastructure_costs": 5.50,
      "fixed_costs": 250.00,
      "total": 1255.50
    },
    
    "margin": {
      "gross_profit": 194.50,
      "gross_margin_percent": 13.41,
      "per_session": 0.00389,
      "per_span": 0.0000389
    },
    
    "break_even_analysis": {
      "current_utilization": "profitable",
      "break_even_sessions": 43150,
      "break_even_spans": 4315000
    },
    
    "recommendations": [
      {
        "type": "pricing_adjustment",
        "message": "Consider increasing session pricing to improve margins",
        "suggested_change": "Increase multiplier from 0.01 to 0.012",
        "impact": "+$100/month revenue"
      }
    ]
  }
}

​
3. Error Handling

​
Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid pricing model configuration",
    "details": [
      {
        "field": "rules[0].tiers[2].upto",
        "code": "INVALID_VALUE",
        "message": "Final tier must have upto: 'unlimited'"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://docs.example.com/errors/VALIDATION_ERROR"
  }
}

​
Error Codes

HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid request body
400INVALID_MODEL_IDModel ID format is invalid
400INVALID_RULE_CONFIGRule configuration is invalid
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENInsufficient permissions
404MODEL_NOT_FOUNDPricing model does not exist
404VERSION_NOT_FOUNDSpecified version does not exist
409VERSION_CONFLICTVersion already exists
409MODEL_IN_USECannot delete model assigned to customers
422SIMULATION_ERRORUnable to process simulation
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

​
4. Webhooks

Subscribe to pricing model events.

​
Available Events

EventDescription
pricing_model.createdNew model created
pricing_model.updatedModel updated (new version)
pricing_model.activatedModel status changed to active
pricing_model.archivedModel archived
simulation.completedBatch simulation completed

​
Webhook Payload

{
  "id": "evt_abc123",
  "type": "pricing_model.updated",
  "created_at": "2024-03-01T10:00:00Z",
  "data": {
    "model_id": "plan_ent_premium_001",
    "version": "1.3.0",
    "previous_version": "1.2.0",
    "changes": ["rules", "platform_fees"]
  }
}

​
5. SDK Usage Examples

​
Python SDK

from pricing_simulator import PricingClient

client = PricingClient(api_key="your_api_key")

# Create a pricing model
model = client.pricing_models.create(
    name="Enterprise Plan",
    currency="USD",
    rules=[
        {
            "display_name": "Spans",
            "telemetry_source": "span",
            "aggregation_method": "COUNT",
            "pricing_type": "tiered",
            "tiers": [
                {"upto": 1000000, "unit_price": 0.00},
                {"upto": 10000000, "unit_price": 0.00005},
                {"upto": "unlimited", "unit_price": 0.00003}
            ]
        }
    ],
    platform_fees={"base_monthly_fee": 500.00}
)

# Run a simulation
result = client.simulations.run(
    model_id=model.model_id,
    usage={
        "spans": 5000000,
        "sessions": 50000
    },
    include_breakdown=True
)

print(f"Total: ${result.summary.total_amount}")
for rule in result.breakdown:
    print(f"  {rule.display_name}: ${rule.amount}")

​
TypeScript SDK

import { PricingClient } from '@company/pricing-simulator';

const client = new PricingClient({ apiKey: 'your_api_key' });

// Create a pricing model
const model = await client.pricingModels.create({
  name: 'Enterprise Plan',
  currency: 'USD',
  rules: [
    {
      displayName: 'Spans',
      telemetrySource: 'span',
      aggregationMethod: 'COUNT',
      pricingType: 'tiered',
      tiers: [
        { upto: 1000000, unitPrice: 0.00 },
        { upto: 10000000, unitPrice: 0.00005 },
        { upto: 'unlimited', unitPrice: 0.00003 }
      ]
    }
  ],
  platformFees: { baseMonthlyFee: 500.00 }
});

// Run a simulation
const result = await client.simulations.run({
  modelId: model.modelId,
  usage: {
    spans: 5000000,
    sessions: 50000
  },
  includeBreakdown: true
});

console.log(`Total: $${result.summary.totalAmount}`);

​
6. Rate Limits

EndpointRate Limit
GET /pricing-models100/minute
GET /pricing-models/{id}200/minute
POST /pricing-models20/minute
PUT/PATCH /pricing-models/{id}20/minute
POST /pricing-models/simulate50/minute
POST /pricing-models/simulate/batch10/minute
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709294400

​
7. Pagination

List endpoints use cursor-based pagination for consistent results: 
{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6Imxhc3RfaWQiLCJ0cyI6MTcwOTI5NDQwMH0=",
    "total_count": 150
  }
}
Use the cursor parameter to fetch the next page: 
GET /v1/pricing-models?cursor=eyJpZCI6Imxhc3RfaWQiLCJ0cyI6MTcwOTI5NDQwMH0=

​
Best Practices

Always test new pricing models in shadow mode before going live. Run simulations with real usage data, share results with your team, and validate that margins meet your targets.
Use semantic versioning (1.0.0, 1.1.0, 2.0.0) and include change summaries. This creates an audit trail and makes it easy to roll back if needed.
Don’t just look at aggregate metrics. Run margin analysis per customer to identify who’s profitable and who’s not. This informs both pricing and product decisions.
Combine base fees, usage tiers, and overage charges. Hybrid models give you predictable baseline revenue while protecting margins on high usage.
Always run “what-if” simulations at 2x, 5x, and 10x your current usage. Your pricing should scale profitably as you grow.
When changing pricing, grandfather existing customers or give 60-90 days notice. Use the simulator to quantify impact and prepare customer communications.

​
Pricing Strategies for AI Agents

Based on patterns from successful AI agent companies:
Company StageRecommended ModelWhy
Pre-launch / BetaFlat fee or freeGather usage data, validate product-market fit
Early Revenue (0-50 customers)Simple tiered pricingEasy to explain, predictable for customers
Growth (50-500 customers)Usage-based with tiersScales with value, protects margins
Scale (500+ customers)Hybrid modelBase fee + usage ensures minimum revenue per customer

​
Anti-Patterns to Avoid

Don’t: Charge flat fees when usage varies 10x+ between customers
  • Result: Either lose money on power users or overprice light users
Don’t: Add usage-based pricing without monitoring COGS
  • Result: Revenue grows but margins shrink (the “unprofitable growth” trap)
Don’t: Surprise customers with huge bills
  • Result: Churn spikes, negative word-of-mouth
Don’t: Change pricing without testing impact first
  • Result: Unexpected revenue loss or customer backlash

​
Quick Reference

​
When to Use the Pricing Simulator

✅ Use it for:
  • Designing initial pricing for a new product
  • Switching from flat to usage-based pricing
  • Adding new billable features or metrics
  • Optimizing margins on existing pricing
  • Validating pricing changes before rollout
  • Understanding per-customer economics
  • Modeling growth scenarios
❌ Don’t need it for:
  • Simple flat-fee pricing with no usage component
  • One-time services with no recurring revenue
  • Products with fixed costs and no variable usage

​
Next Steps

Build Your First Model

Follow the API guide to create your first pricing model via SDK or API

Run a Simulation

Test your model against usage data and see projected revenue

Margin Analysis

Calculate true profitability by connecting your cost data

Billing Integration

Connect your pricing model to billing webhooks for production use
Pro tip for AI agent founders: Pricing is the fastest lever to improve revenue. A 10% pricing optimization can have the same impact as a 30% increase in sales—without changing your product or spending more on marketing.