Upgrading Billing Transparency: What Developers Need to Know About the New AI/ML API v2 Billing Endpoints

Billing just got clearer. The AI/ML API v2 update brings detailed balance insights, auto top-up configuration, and USD-based metrics. Learn what’s changing and how to upgrade before April 15, 2026.

Effective April 15, 2026, the AI/ML API is rolling out a set of meaningful changes to how billing data is exposed through the API. The update introduces two new v2 billing endpoints that offer significantly more detail than their predecessor, and formally deprecates the older v1 balance endpoint along with the credits_used field. Whether you are managing automated top-ups, monitoring account balances programmatically, or building internal dashboards on top of billing data, this is worth your attention.

Here is a clear breakdown of what is changing, what the new endpoints return, and what actions your integration may require.

Why This Update Matters

Billing visibility is a common pain point for developers working with AI APIs. Knowing your current balance is only part of the picture, understanding how auto-top-up is configured, what currency your account operates in, and what the threshold triggers are can make the difference between a seamless production environment and an unexpected service interruption.

The v2 billing endpoints have been designed with those use cases in mind, consolidating essential billing metadata into a clean, well-structured response format.

The New Billing Endpoints

1. GET /v2/billing — Current Balance Summary

For integrations that simply need to check a user's current balance, the new lightweight summary endpoint is the right tool.

Endpoint:

`GET https://api.aimlapi.com/v2/billing`

Response Fields:

Field	Type	Description
current_balance	number	The user's current account balance, denominated in USD.
currency	string	Currency code — always "USD" at this time.

2. GET /v2/billing/detail — Extended Billing Information

For integrations that require a fuller picture, the detail endpoint goes further, returning user identity data, balance, and the full configuration of any auto-top-up settings tied to the account.

Endpoint:

`GET https://api.aimlapi.com/v2/billing/detail`

Response Fields:

Field	Type	Description
userId	number	Unique numeric identifier for the user account.
email	string	Email address associated with the account.
current_balance	number	Current balance in USD.
currency	string	Currency code — always "USD".
autotopup_settings.is_enabled	boolean	Whether the auto top-up feature is currently active.
autotopup_settings.threshold	number	Balance level (in USD) at which a top-up is automatically triggered.
autotopup_settings.amount	number	The USD amount charged each time an auto top-up is triggered.
autotopup_settings.currency	string	Currency for top-up transactions — always "USD".

Authentication

Both endpoints authenticate using your existing API key. No new credentials or scopes are required — just pass your key as you would for any other authenticated request.

What Is Being Deprecated

The v1 Balance Endpoint

The legacy endpoint below is being retired:

`GET https://api.aimlapi.com/v1/billing/balance [DEPRECATED]`

If your integration currently calls this endpoint, you will need to migrate to either /v2/billing or /v2/billing/detail before April 15, 2026. The v2 endpoints return the same core data with additional context, so the swap is straightforward.

The credits_used Field

The credits_used field is also being removed from API responses. In its place, the usd_spent field is now available across the relevant API responses and provides a direct USD figure, eliminating any ambiguity around credit conversion rates.

Action required: Update any code that reads or processes credits_used to use usd_spent instead.

Deprecated	Replacement
GET /v1/billing/balance credits_used field	GET /v2/billing GET /v2/billing/detail usd_spent field

What Stays the Same

These updates are purely additive from a data perspective. No existing account data is being modified or removed. All historical records, balances, and account settings will remain intact following the transition. The only thing being phased out is the legacy endpoint and the outdated field name.

Migration Checklist

Replace calls to /v1/billing/balance with /v2/billing or /v2/billing/detail.
Update any logic that reads credits_used to reference usd_spent instead.
Verify API key authentication is correctly passed in the request header.
Test your updated integration against the new endpoints before April 15, 2026.
Review any downstream logic that parses billing responses for unexpected field changes.

These changes reflect a broader trend toward clearer, more developer-friendly billing APIs — moving away from abstract credit units toward transparent USD-denominated figures. The new endpoint structure also makes it easier to build robust account management tooling without needing to make multiple calls or maintain custom conversion logic.

Most integrations will require only minor adjustments. If you run into any issues during the migration or need clarification on specific response field behavior, reach out to the AI/ML API support team at [email protected].

Example H2