Understanding billing and usage tracking

To manage costs and track usage effectively, it's important to understand how your API activity translates into billable units. Billing models vary depending on the deployment platform, be it IBM Cloud or AWS. They are also based on different metrics such as Monthly Active Users (MAUs), Monthly Active Voice Users (MAVUs), messages, minutes, and Resource Units (RUs).

Platform-specific usage metrics

Billing behavior in watsonx Orchestrate varies depending on the platform where watsonx Orchestrate is deployed. While the core concepts such as tracking user interactions and document processing remain consistent, the way these activities are measured and billed differs between IBM Cloud and AWS.

The following section outlines the key usage metrics and billing conversions specific to each platform.

IBM Cloud

On IBM Cloud, billing is primarily based on Monthly Active Users (MAUs):

  1. Monthly Active Users (MAU):

    Each MAU represents a unique user who interacts with watsonx Orchestrate during a calendar month. To track MAUs accurately, you must include a customer_id in your API request context. The system uses this identifier to recognize each user and counts a distinct customer_id once per month, regardless of how many interactions that user initiates.

    Each MAU includes up to 50 messages per month. If a user sends more than 50 messages, the system counts an additional MAU for every extra set of 50 messages.

  2. Monthly Active Voice Users (MAVU):

    If your users interact through voice channels such as phone, the system counts them as MAVUs in addition to MAUs. Each voice-based MAU also counts as a MAVU.

  3. Document processing:

    You track document processing based on the number of pages that are processed through document-related tools. It converts this usage internally to MAUs or other billing units, depending on your deployment platform. On IBM Cloud, the conversion rate is 15 pages = 1 MAU (Monthly Active User).

AWS

On AWS, billing is based on Resource Units (RUs):

  1. MAU to RU conversion:

    • Essentials plan: 6 MAUs = 1 RU
    • Voice interactions: 10 MAVUs = 1 RU

  2. Document Processing: Billed separately from MAUs, at a rate of 100 pages = 1 RU

Tracking and identifying users

Usage tracking in watsonx Orchestrate relies on identifiers that are passed in the API request context. When a request reaches the /runs API, regardless of the originating channel (such as Orchestrate Chat, ADK, embedded chat, or any other integrated interface) the system checks for a customer_id in the request context.

The customer_id is used to track how many unique users interact with watsonx Orchestrate each month, enabling accurate usage metrics across all supported channels.

The system applies the following logic to identify users:

  • If you include customer_id in the context: The system uses it as the unique identifier and forwards it to the Unified Billing Service for MAU calculation.

  • If you don't include customer_id: The system defaults to using thread_id as the identifier. This fallback mechanism helps ensure that every interaction is tracked, but it can lead to inflated MAU counts if multiple threads are initiated by the same user without a consistent identifier.