Billing & Usage Tracking API

Overview

The Billing & Usage Tracking API provides comprehensive cost monitoring, usage analytics, and billing management for AI gateway services. This API tracks usage across providers, models, and tiers with real-time cost calculation and detailed reporting capabilities.

Endpoints

GET /api/v1/usage                    # Get usage statistics
GET /api/v1/usage/export             # Export usage data
POST /api/v1/usage/track            # Track usage event (internal)
GET /api/v1/billing/reports         # Get billing reports
POST /api/v1/billing/alerts         # Configure billing alerts

Authentication

Requires valid API key or session authentication. Billing data access is restricted by company and role permissions.

Rate Limits

All Tiers: 10,000 requests/hour (billing endpoints are not heavily rate-limited)

Get Usage Statistics

Endpoint

GET /api/v1/usage

Query Parameters

Parameter	Type	Description	Default
`startDate`	string	Start date (ISO 8601)	30 days ago
`endDate`	string	End date (ISO 8601)	Now
`granularity`	enum	`hour`, `day`, `week`, `month`	`day`
`groupBy`	enum	`provider`, `model`, `tier`, `user`	`provider`
`companyId`	string	Company ID (admin only)	Current user's company

Response Format

json

{
  "success": true,
  "data": {
    "period": {
      "start": "string (ISO 8601)",
      "end": "string (ISO 8601)",
      "granularity": "day"
    },
    "summary": {
      "totalRequests": number,
      "totalTokens": number,
      "totalCost": number,
      "currency": "USD",
      "avgCostPerRequest": number,
      "avgCostPerToken": number
    },
    "byProvider": {
      "provider_name": {
        "requests": number,
        "tokens": number,
        "cost": number,
        "avgLatency": number,
        "errorRate": number,
        "models": {
          "model_name": {
            "requests": number,
            "tokens": number,
            "cost": number
          }
        }
      }
    },
    "byTier": {
      "enterprise": {
        "requests": number,
        "tokens": number,
        "cost": number,
        "users": number
      },
      "professional": {
        "requests": number,
        "tokens": number,
        "cost": number,
        "users": number
      },
      "standard": {
        "requests": number,
        "tokens": number,
        "cost": number,
        "users": number
      },
      "free": {
        "requests": number,
        "tokens": number,
        "cost": number,
        "users": number
      }
    },
    "timeline": [
      {
        "timestamp": "string (ISO 8601)",
        "requests": number,
        "tokens": number,
        "cost": number,
        "breakdown": {
          "provider_name": {
            "requests": number,
            "cost": number
          }
        }
      }
    ],
    "topUsers": [
      {
        "userId": "string",
        "userName": "string",
        "requests": number,
        "cost": number,
        "tier": "string"
      }
    ]
  }
}

Export Usage Data

Endpoint

GET /api/v1/usage/export

Query Parameters

Parameter	Type	Description
`format`	enum	`csv`, `json`, `xlsx`
`startDate`	string	Start date (ISO 8601)
`endDate`	string	End date (ISO 8601)
`includeDetails`	boolean	Include request-level details

Response

Returns file download with usage data in requested format.

CSV Format:

csv

Date,Provider,Model,Tier,UserId,Requests,Tokens,Cost,AvgLatency,ErrorRate
2024-01-15,openai,gpt-4-turbo,enterprise,user_123,450,125000,12.50,520,0.02
2024-01-15,anthropic,claude-3-sonnet,professional,user_456,230,89000,5.34,680,0.01

Track Usage Event (Internal)

Endpoint

POST /api/v1/usage/track

Request Body

json

{
  "eventId": "string (required)",
  "timestamp": "string (ISO 8601)",
  "userId": "string (required)",
  "companyId": "string (required)",
  "tier": "enterprise" | "professional" | "standard" | "free",
  "request": {
    "id": "string (required)",
    "type": "completion" | "chat" | "embedding" | "image",
    "provider": "string (required)",
    "model": "string (required)",
    "promptTokens": number,
    "completionTokens": number,
    "totalTokens": number
  },
  "billing": {
    "cost": number,
    "currency": "USD",
    "breakdown": {
      "baseCost": number,
      "markupPercentage": number,
      "discount": number,
      "finalCost": number
    },
    "billingCycle": "monthly" | "quarterly" | "annual"
  },
  "performance": {
    "latency": number,
    "success": boolean,
    "errorCode": "string",
    "retries": number
  },
  "metadata": {
    "region": "string",
    "endpoint": "string",
    "features": ["string"]
  }
}

Get Billing Reports

Endpoint

GET /api/v1/billing/reports

Query Parameters

Parameter	Type	Description
`reportType`	enum	`monthly`, `quarterly`, `annual`, `custom`
`year`	number	Year for report
`month`	number	Month for report (1-12)
`companyId`	string	Company ID (admin only)

Response Format

json

{
  "success": true,
  "report": {
    "reportId": "string",
    "period": {
      "start": "string (ISO 8601)",
      "end": "string (ISO 8601)",
      "timezone": "string"
    },
    "company": {
      "id": "string",
      "name": "string",
      "tier": "enterprise",
      "billingCycle": "monthly"
    },
    "usage": {
      "totalRequests": number,
      "totalTokens": number,
      "byProvider": {
        "openai": {
          "requests": 15420,
          "tokens": 4250000,
          "cost": 425.50
        },
        "anthropic": {
          "requests": 8930,
          "tokens": 2100000,
          "cost": 189.25
        }
      },
      "byModel": {
        "gpt-4-turbo": {
          "requests": 12500,
          "tokens": 3800000,
          "cost": 380.00
        },
        "claude-3-sonnet": {
          "requests": 8930,
          "tokens": 2100000,
          "cost": 189.25
        }
      },
      "byDay": [
        {
          "date": "2024-01-01",
          "requests": 1250,
          "tokens": 340000,
          "cost": 34.50
        }
      ]
    },
    "costs": {
      "subtotal": 614.75,
      "discounts": [
        {
          "type": "volume_discount",
          "amount": 61.48,
          "reason": "10% volume discount for >5M tokens"
        },
        {
          "type": "annual_prepay",
          "amount": 30.74,
          "reason": "Annual payment discount"
        }
      ],
      "credits": 0.00,
      "tax": 44.25,
      "total": 566.78,
      "currency": "USD"
    },
    "limits": {
      "tier": "enterprise",
      "quotas": {
        "requests": {
          "used": 24350,
          "limit": 1000000,
          "percentage": 2.4
        },
        "tokens": {
          "used": 6350000,
          "limit": 100000000,
          "percentage": 6.4
        },
        "cost": {
          "used": 566.78,
          "limit": 10000.00,
          "percentage": 5.7
        }
      },
      "warnings": []
    },
    "invoice": {
      "number": "INV-2024-001",
      "dueDate": "2024-02-15",
      "status": "pending",
      "paymentMethod": "credit_card_****1234"
    }
  }
}

Configure Billing Alerts

Endpoint

POST /api/v1/billing/alerts

Request Body

json

{
  "alertId": "string",
  "name": "string (required)",
  "type": "cost_threshold" | "usage_threshold" | "quota_warning",
  "conditions": {
    "metric": "cost" | "requests" | "tokens",
    "threshold": number,
    "period": "daily" | "weekly" | "monthly",
    "comparison": "greater_than" | "less_than" | "equals"
  },
  "actions": [
    {
      "type": "email" | "webhook" | "slack",
      "target": "string",
      "template": "string"
    }
  ],
  "enabled": boolean
}

Response

json

{
  "success": true,
  "alertId": "string",
  "message": "Billing alert configured successfully"
}

Cost Calculation

Pricing Model

The gateway applies a tiered markup structure on provider costs:

Tier	Provider Cost Markup	Volume Discount	Features
Free	+100%	None	Basic routing only
Standard	+50%	5% at 1M tokens	Standard features
Professional	+25%	10% at 5M tokens	Advanced features
Enterprise	+10%	15% at 50M tokens	All features + SLA

Example Cost Calculation

javascript

function calculateCost(providerCost, tier, monthlyVolume) {
  const markups = {
    free: 2.0,        // 100% markup
    standard: 1.5,    // 50% markup
    professional: 1.25, // 25% markup
    enterprise: 1.1   // 10% markup
  };
  
  const volumeDiscounts = {
    standard: monthlyVolume >= 1000000 ? 0.05 : 0,
    professional: monthlyVolume >= 5000000 ? 0.10 : 0,
    enterprise: monthlyVolume >= 50000000 ? 0.15 : 0
  };
  
  const baseMarkup = markups[tier] || markups.free;
  const discount = volumeDiscounts[tier] || 0;
  
  const markedUpCost = providerCost * baseMarkup;
  const finalCost = markedUpCost * (1 - discount);
  
  return {
    providerCost,
    markupPercentage: (baseMarkup - 1) * 100,
    discount: discount * 100,
    finalCost
  };
}

// Example
const billing = calculateCost(0.02, 'professional', 8000000);
// Result: { providerCost: 0.02, markupPercentage: 25, discount: 10, finalCost: 0.0225 }

Error Responses

400 Bad Request

json

{
  "error": "Invalid date range",
  "message": "End date must be after start date"
}

403 Forbidden

json

{
  "error": "Access denied",
  "message": "Insufficient permissions to view billing data"
}

429 Too Many Requests

json

{
  "error": "Export rate limit exceeded",
  "retryAfter": 3600,
  "message": "Export requests limited to 10 per hour"
}

Example Usage

JavaScript Dashboard Integration

javascript

class BillingDashboard {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://app.veriprompt.tech';
  }
  
  async getUsageStats(period = '30d', groupBy = 'provider') {
    const endDate = new Date().toISOString();
    const startDate = new Date(Date.now() - (30 * 24 * 60 * 60 * 1000)).toISOString();
    
    const response = await fetch(`${this.baseUrl}/api/v1/usage?` + new URLSearchParams({
      startDate,
      endDate,
      granularity: 'day',
      groupBy
    }), {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    return await response.json();
  }
  
  async exportUsageData(format = 'csv', days = 30) {
    const endDate = new Date().toISOString();
    const startDate = new Date(Date.now() - (days * 24 * 60 * 60 * 1000)).toISOString();
    
    const response = await fetch(`${this.baseUrl}/api/v1/usage/export?` + new URLSearchParams({
      format,
      startDate,
      endDate,
      includeDetails: 'true'
    }), {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    if (format === 'json') {
      return await response.json();
    } else {
      return await response.blob();
    }
  }
  
  async setupCostAlert(threshold, period = 'monthly') {
    const alertConfig = {
      name: `Cost Alert - $${threshold}`,
      type: 'cost_threshold',
      conditions: {
        metric: 'cost',
        threshold,
        period,
        comparison: 'greater_than'
      },
      actions: [
        {
          type: 'email',
          target: 'billing@company.com',
          template: 'cost_threshold_exceeded'
        }
      ],
      enabled: true
    };
    
    const response = await fetch(`${this.baseUrl}/api/v1/billing/alerts`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(alertConfig)
    });
    
    return await response.json();
  }
  
  async generateMonthlyCostReport() {
    const stats = await this.getUsageStats('30d', 'provider');
    
    const report = {
      period: '30 days',
      totalCost: stats.data.summary.totalCost,
      totalRequests: stats.data.summary.totalRequests,
      avgCostPerRequest: stats.data.summary.avgCostPerRequest,
      providers: Object.entries(stats.data.byProvider).map(([name, data]) => ({
        name,
        cost: data.cost,
        requests: data.requests,
        costPercentage: (data.cost / stats.data.summary.totalCost * 100).toFixed(1)
      })).sort((a, b) => b.cost - a.cost),
      trends: stats.data.timeline.map(day => ({
        date: day.timestamp.split('T')[0],
        cost: day.cost,
        requests: day.requests
      }))
    };
    
    return report;
  }
}

// Usage
const billing = new BillingDashboard(apiKey);

// Get current month usage
const usage = await billing.getUsageStats('30d');
console.log(`Total cost: $${usage.data.summary.totalCost}`);
console.log(`Total requests: ${usage.data.summary.totalRequests}`);

// Set up cost alert
await billing.setupCostAlert(1000, 'monthly');
console.log('Cost alert configured for $1,000/month');

// Export detailed usage data
const csvData = await billing.exportUsageData('csv', 90);
console.log('90-day usage data exported');

Python Cost Analysis

python

import requests
import pandas as pd
from datetime import datetime, timedelta
import matplotlib.pyplot as plt

class CostAnalyzer:
    def __init__(self, api_key, base_url="https://app.veriprompt.tech"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    
    def get_usage_data(self, days=30, granularity='day'):
        """Get usage data for analysis"""
        end_date = datetime.now().isoformat()
        start_date = (datetime.now() - timedelta(days=days)).isoformat()
        
        params = {
            'startDate': start_date,
            'endDate': end_date,
            'granularity': granularity,
            'groupBy': 'provider'
        }
        
        response = requests.get(
            f'{self.base_url}/api/v1/usage',
            headers=self.headers,
            params=params
        )
        
        response.raise_for_status()
        return response.json()['data']
    
    def analyze_cost_trends(self, days=30):
        """Analyze cost trends and predict future costs"""
        data = self.get_usage_data(days)
        
        # Convert timeline to DataFrame
        df = pd.DataFrame(data['timeline'])
        df['date'] = pd.to_datetime(df['timestamp'])
        df['cost'] = df['cost'].astype(float)
        
        # Calculate trends
        daily_avg = df['cost'].mean()
        weekly_avg = df.groupby(df['date'].dt.isocalendar().week)['cost'].sum().mean()
        monthly_projection = daily_avg * 30
        
        # Detect cost spikes (days with >2x average cost)
        cost_spikes = df[df['cost'] > (daily_avg * 2)]
        
        return {
            'daily_average': daily_avg,
            'weekly_average': weekly_avg,
            'monthly_projection': monthly_projection,
            'cost_spikes': len(cost_spikes),
            'trend': self._calculate_trend(df['cost']),
            'data': df
        }
    
    def _calculate_trend(self, costs):
        """Calculate cost trend (increasing/decreasing/stable)"""
        recent_avg = costs.tail(7).mean()  # Last 7 days
        previous_avg = costs.head(-7).tail(7).mean()  # Previous 7 days
        
        change_percent = ((recent_avg - previous_avg) / previous_avg) * 100
        
        if change_percent > 10:
            return 'increasing'
        elif change_percent < -10:
            return 'decreasing'
        else:
            return 'stable'
    
    def optimize_costs(self, usage_data):
        """Suggest cost optimization strategies"""
        suggestions = []
        
        # Analyze provider costs
        providers = usage_data['byProvider']
        total_cost = sum(p['cost'] for p in providers.values())
        
        for provider, data in providers.items():
            cost_percentage = (data['cost'] / total_cost) * 100
            
            if cost_percentage > 50:
                suggestions.append(f"Consider load balancing: {provider} accounts for {cost_percentage:.1f}% of costs")
            
            if data['errorRate'] > 0.05:
                suggestions.append(f"High error rate for {provider} ({data['errorRate']:.1%}) may be inflating costs")
            
            # Check for expensive models
            for model, model_data in data.get('models', {}).items():
                if model_data['cost'] / model_data['requests'] > 0.01:  # $0.01 per request
                    suggestions.append(f"Consider cheaper alternative to {provider}:{model}")
        
        return suggestions
    
    def generate_cost_report(self, days=30):
        """Generate comprehensive cost report"""
        usage_data = self.get_usage_data(days)
        trends = self.analyze_cost_trends(days)
        optimizations = self.optimize_costs(usage_data)
        
        report = {
            'period': f'{days} days',
            'summary': {
                'total_cost': usage_data['summary']['totalCost'],
                'total_requests': usage_data['summary']['totalRequests'],
                'avg_cost_per_request': usage_data['summary']['avgCostPerRequest'],
                'daily_average': trends['daily_average'],
                'monthly_projection': trends['monthly_projection']
            },
            'trends': {
                'direction': trends['trend'],
                'cost_spikes': trends['cost_spikes']
            },
            'top_providers': sorted([
                {
                    'name': name,
                    'cost': data['cost'],
                    'percentage': (data['cost'] / usage_data['summary']['totalCost']) * 100
                }
                for name, data in usage_data['byProvider'].items()
            ], key=lambda x: x['cost'], reverse=True)[:5],
            'optimizations': optimizations,
            'alerts': self._check_cost_alerts(usage_data, trends)
        }
        
        return report
    
    def _check_cost_alerts(self, usage_data, trends):
        """Check for cost-related alerts"""
        alerts = []
        
        if trends['trend'] == 'increasing':
            alerts.append("📈 Costs are trending upward")
        
        if trends['monthly_projection'] > 1000:  # Example threshold
            alerts.append(f"💰 Monthly projection (${trends['monthly_projection']:.2f}) exceeds budget")
        
        if trends['cost_spikes'] > 5:
            alerts.append(f"⚠️  {trends['cost_spikes']} cost spikes detected")
        
        return alerts
    
    def visualize_costs(self, days=30):
        """Create cost visualization"""
        trends = self.analyze_cost_trends(days)
        df = trends['data']
        
        plt.figure(figsize=(12, 8))
        
        # Daily costs
        plt.subplot(2, 2, 1)
        plt.plot(df['date'], df['cost'])
        plt.title('Daily Costs')
        plt.xlabel('Date')
        plt.ylabel('Cost ($)')
        plt.xticks(rotation=45)
        
        # Cost distribution by provider
        usage_data = self.get_usage_data(days)
        providers = usage_data['byProvider']
        
        plt.subplot(2, 2, 2)
        provider_names = list(providers.keys())
        provider_costs = [providers[p]['cost'] for p in provider_names]
        plt.pie(provider_costs, labels=provider_names, autopct='%1.1f%%')
        plt.title('Cost Distribution by Provider')
        
        # Requests vs Cost
        plt.subplot(2, 2, 3)
        plt.scatter(df['requests'], df['cost'])
        plt.xlabel('Daily Requests')
        plt.ylabel('Daily Cost ($)')
        plt.title('Requests vs Cost')
        
        # Cost trend
        plt.subplot(2, 2, 4)
        df['cost_ma'] = df['cost'].rolling(window=7).mean()  # 7-day moving average
        plt.plot(df['date'], df['cost'], alpha=0.3, label='Daily')
        plt.plot(df['date'], df['cost_ma'], label='7-day average')
        plt.title('Cost Trend')
        plt.xlabel('Date')
        plt.ylabel('Cost ($)')
        plt.legend()
        plt.xticks(rotation=45)
        
        plt.tight_layout()
        plt.show()

# Usage
analyzer = CostAnalyzer(api_key)

# Generate comprehensive cost report
report = analyzer.generate_cost_report(30)

print(f"📊 Cost Report - {report['period']}")
print(f"💰 Total Cost: ${report['summary']['total_cost']:.2f}")
print(f"📈 Monthly Projection: ${report['summary']['monthly_projection']:.2f}")
print(f"📉 Trend: {report['trends']['direction']}")

print("\n🏆 Top Providers:")
for provider in report['top_providers']:
    print(f"  {provider['name']}: ${provider['cost']:.2f} ({provider['percentage']:.1f}%)")

if report['optimizations']:
    print("\n💡 Optimization Suggestions:")
    for suggestion in report['optimizations']:
        print(f"  • {suggestion}")

if report['alerts']:
    print("\n🚨 Alerts:")
    for alert in report['alerts']:
        print(f"  {alert}")

# Visualize costs
analyzer.visualize_costs(30)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

Webhook Integration

Configure webhooks to receive real-time billing notifications:

javascript

// Webhook payload for cost threshold alert
{
  "webhookId": "webhook_123",
  "timestamp": "2024-01-15T10:30:00Z",
  "event": {
    "type": "billing.threshold_exceeded",
    "severity": "warning"
  },
  "data": {
    "companyId": "company_789",
    "threshold": {
      "type": "monthly_cost",
      "limit": 1000,
      "current": 1150,
      "percentage": 115
    },
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    }
  },
  "retry": {
    "attempt": 1,
    "maxAttempts": 3
  },
  "signature": "sha256=..."
}

Best Practices

Cost Management

Set Budgets: Configure monthly/quarterly budget limits
Monitor Trends: Track daily costs for unexpected spikes
Optimize Regularly: Review provider and model efficiency monthly
Use Alerts: Set up proactive cost and quota alerts
Analyze Usage: Regular analysis of usage patterns for optimization

Data Export

Regular Backups: Export usage data monthly for compliance
Audit Trail: Maintain detailed request-level logs
Cost Allocation: Export by department/project for internal billing
Trend Analysis: Use exported data for capacity planning

Changelog

Version 1.0.0 (Current)

Initial release
Real-time usage tracking
Multi-format data export
Comprehensive billing reports
Cost alert system
Provider cost analysis

Billing & Usage Tracking API ​

Overview ​

Endpoints ​

Authentication ​

Rate Limits ​

Get Usage Statistics ​

Endpoint ​

Query Parameters ​

Response Format ​

Export Usage Data ​

Endpoint ​

Query Parameters ​

Response ​

Track Usage Event (Internal) ​

Endpoint ​

Request Body ​

Get Billing Reports ​

Endpoint ​

Query Parameters ​

Response Format ​

Configure Billing Alerts ​

Endpoint ​

Request Body ​

Response ​

Cost Calculation ​

Pricing Model ​

Example Cost Calculation ​

Error Responses ​

400 Bad Request ​

403 Forbidden ​

429 Too Many Requests ​

Example Usage ​

JavaScript Dashboard Integration ​

Python Cost Analysis ​

Webhook Integration ​

Best Practices ​

Cost Management ​

Data Export ​

Changelog ​

Version 1.0.0 (Current) ​

Billing & Usage Tracking API

Overview

Endpoints

Authentication

Rate Limits

Get Usage Statistics

Endpoint

Query Parameters

Response Format

Export Usage Data

Endpoint

Query Parameters

Response

Track Usage Event (Internal)

Endpoint

Request Body

Get Billing Reports

Endpoint

Query Parameters

Response Format

Configure Billing Alerts

Endpoint

Request Body

Response

Cost Calculation

Pricing Model

Example Cost Calculation

Error Responses

400 Bad Request

403 Forbidden

429 Too Many Requests

Example Usage

JavaScript Dashboard Integration

Python Cost Analysis

Webhook Integration

Best Practices

Cost Management

Data Export

Changelog

Version 1.0.0 (Current)