Usage Reporting and Billing

Usage reporting is the core functionality that enables AI agents to monetize their services in real-time. As an AI agent developer, you report each usage event as it happens, and the system handles:

Real-time Usage Tracking: What the user did (API calls, token usage, processing time, etc.)
Cost Calculation: How much the usage costs based on your pricing
Instant User Billing: Whether and how much to charge the user immediately
Transparent Reporting: Detailed reports for both you and your users

How Usage Reporting Works

When a user interacts with your AI agent, you:

Process the request using your AI models
Calculate the cost based on your pricing strategy
Report the usage to Reload with all relevant details
Optionally charge the user immediately for the usage

This happens in real-time for each interaction, providing transparent billing and immediate cost feedback to users.

What You Can Report

Core Usage Data:

AI Agent ID (aiAgentId): REQUIRED - The unique identifier of the AI Agent that processed the usage. This field is mandatory for all usage reports and identifies which specific AI Agent within your organization handled the request. You can create and manage AI Agents through the AI Agent Developer Portal.
Description: REQUIRED - Detailed description of what the user did. This field provides a clear explanation of what the usage represents, helping users understand what they're being charged for.
Usage Type: What kind of usage occurred (e.g., "token_usage", "api_call", "processing_time")\
Short Description: Optional brief description of the usage
Total Cost (REQUIRED): The total cost of this usage in USD

AI-Specific Data:

Model Information: Which AI model was used (e.g., "gpt-4", "claude-3")
Provider: The AI provider (e.g., "OpenAI", "Anthropic")
Token Usage: Input tokens, output tokens, and total tokens
Processing Time: How long the request took to process
Model Parameters: Temperature, max tokens, and other settings

AI Agent Internal System (Optional):

Internal Tokens or Credits (internalTokensOrCredits): Number of tokens or credits consumed from your internal system. This field allows you to track your own internal token/credit consumption alongside USD billing. For example, if you offer users 10 million tokens for $100, you can track both the USD cost and how many of your internal tokens were consumed. This provides transparency to users about both monetary costs and resource consumption.

Billing Control:

Charge User: Whether to charge the user immediately (true/false)
Idempotency Key: Unique key to prevent duplicate charges

Real-Time Charging Strategies

Pay-Per-Use (Recommended) Charge users immediately for each usage event:
- User makes a request → You process it → Report usage with chargeUser: true
- User is charged instantly for that specific usage
- Provides transparent, real-time billing
Usage Tracking Only Track usage without charging (useful for free tiers or trials):
- User makes a request → You process it → Report usage with chargeUser: false
- Usage is tracked but user is not charged
- Useful for free tiers, analytics, or trial periods

Idempotency for Reliability

The API supports idempotency keys to prevent duplicate charges. If you send the same idempotency key twice, the second request will return the same result without creating a duplicate charge.

Best Practices:

Use unique idempotency keys for each usage event
Include timestamp and user ID in the key (not required though)
Store idempotency keys to handle retries gracefully