AI Credits: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Display an account's AI credit balance

Apps that offer AI features often show account owners how many credits they have left. The AI Credits API returns the full balance in a single call, so you can render it in a dashboard or settings page.

To display an account's AI credit balance:

1. Call Get Balance to retrieve the account's current balance. The request takes no parameters.
2. Read periodicCredits.balance for remaining recurring credits and topUpCredits.balance for remaining top-up credits, then show the total available as periodicCredits.balance + (topUpCredits.balance ?? 0).
3. Optionally, use creditBalanceBreakdown to display credits from each source separately.
4. Refresh the balance after AI actions so the displayed total stays accurate.

Gate an AI feature on available credits

Before running an AI action that consumes credits, check whether the account has enough credits and prompt the account to top up if it doesn't.

To gate an AI feature on available credits:

1. Call Get Balance to retrieve the account's current balance.
2. Calculate the total available credits as periodicCredits.balance + (topUpCredits.balance ?? 0).
3. Compare the available credits with the estimated cost of the action, and run the AI action when there are enough credits.
4. When there aren't enough credits, prompt the account to upgrade their plan or purchase top-up credits, and don't run the action.