> For the complete documentation index, see [llms.txt](https://docs.uibakery.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uibakery.io/build-with-ai/usage-credits-monitoring.md). # Usage credits monitoring You can monitor usage credits via the Instance API endpoint or by setting up the low-credit email alerts. ### Credits endpoint Use the Instance API endpoint to read usage credits for a workspace by slug. ``` GET /api/instance/organization/{slug}/credits Authorization: Bearer ``` Example: ```bash curl -i https:///api/instance/organization/acme/credits \ -H "Authorization: Bearer $UI_BAKERY_INSTANCE_API_TOKEN" ``` The endpoint returns the standard Instance API response wrapper. The credits balance is in `result`. Example response: ```json { "status": "OK", "message": "Credits balance fetched", "result": { "organizationId": "b6b3e804-bf24-11f0-b596-9514a4f9f5de", "organizationSlug": "acme", "availableCredits": 249.68, "lastTopUpTotalCredits": 250.0, "percentageRemaining": 99.87, "billingDisabled": false } } ``` The endpoint returns customer-facing UI Bakery usage credits, not raw AI/token credits. Result fields:
FieldDescription
organizationIdWorkspace view ID.
organizationSlugWorkspace slug from the request.
availableCreditsRemaining UI Bakery usage credits.
lastTopUpTotalCreditsTotal usage credits from the latest top-up/current balance period.
percentageRemainingRemaining percentage, calculated as availableCredits / lastTopUpTotalCredits * 100, rounded to 2 decimals. May be null if the total is missing or zero.
billingDisabledtrue when credits billing is disabled for the chat service/runtime.
Status codes: | Status | Meaning | Body | | ------ | ----------------------------------------------------------- | ----------------------------- | | `200` | Credits balance returned successfully. | `status`, `message`, `result` | | `403` | Missing or invalid Instance API token. | Instance API auth error body | | `404` | Organization with the given slug was not found. | `status`, `message` | | `502` | Java backend could not fetch credits from the chat service. | `status`, `message` | ### Low-credit alerts The backend includes a scheduled job that checks Workspace credit balances and sends alerts when configured thresholds are reached. Alerts are disabled by default. To deliver alerts, all of the following must be true: * `UI_BAKERY_CREDITS_ALERT_ENABLED=true` * at least one threshold is configured, * at least one delivery channel is configured: email and/or webhook. Alerts are skipped when `billingDisabled=true`. #### Alert thresholds Two threshold types are supported: * absolute usage credits threshold; * percentage remaining threshold. An alert is sent when either configured threshold is reached. Example: ``` UI_BAKERY_CREDITS_ALERT_THRESHOLD_CREDITS=10 UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT=20 ``` This sends an alert when either: * the workspace has 10 usage credits or fewer; or * the workspace has 20% or less of its latest top-up remaining. Use `-1` to disable a threshold: ``` UI_BAKERY_CREDITS_ALERT_THRESHOLD_CREDITS=-1 UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT=20 ``` With this configuration, only the percentage threshold is used. #### Alert configuration variables
VariableDefaultDescription
UI_BAKERY_CREDITS_ALERT_ENABLEDfalseEnables or disables the scheduled low-credit alert job.
UI_BAKERY_CREDITS_ALERT_THRESHOLD_CREDITS-1Absolute usage credits threshold. -1 disables this threshold.
UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT-1Percentage remaining threshold. -1 disables this threshold.
UI_BAKERY_CREDITS_ALERT_EMAIL_ENABLEDtrueEnables email delivery to organization admins.
UI_BAKERY_CREDITS_ALERT_WEBHOOK_URLemptyOptional webhook URL for alert delivery.
UI_BAKERY_CREDITS_ALERT_COOLDOWN_HOURS24Per-organization cooldown after a successful alert. Prevents repeated alerts while credits remain low.
UI_BAKERY_CREDITS_ALERT_CRON0 0 * * * *Spring cron expression for scheduled checks. Spring cron includes seconds.
Important behavior: * The alert job has a hard minimum check interval of 15 minutes. If the cron runs more often, checks are skipped until the next allowed time. * Cooldown is tracked in memory per Java process and resets after backend restart. * Cooldown is recorded only after at least one delivery channel succeeds. * Email and webhook delivery are attempted independently. If one channel fails, the other can still succeed. #### Webhook alerts Set `UI_BAKERY_CREDITS_ALERT_WEBHOOK_URL` to send a `POST` request when credits are low. ``` UI_BAKERY_CREDITS_ALERT_ENABLED=true UI_BAKERY_CREDITS_ALERT_WEBHOOK_URL=https://example.com/credits-alert-webhook UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT=20 ``` Payload example: ```json { "event": "credits.low_balance", "organizationId": "b6b3e804-bf24-11f0-b596-9514a4f9f5de", "organizationSlug": "acme", "availableCredits": 9.5, "lastTopUpTotalCredits": 250.0, "percentageRemaining": 3.8, "billingDisabled": false, "text": "UI Bakery usage credits are low for acme: 9.5 usage credits remaining (3.8%)." } ``` The webhook payload is not the same as the Instance API response. It intentionally includes `event` and `text` for automation/notification tools. The `text` field is included so the payload can be used with Slack-compatible incoming webhooks or automation tools. The webhook request has a 5-second connection/read timeout. ### Email alerts Email alerts are sent to Workspace admins. Enable email delivery: ``` UI_BAKERY_CREDITS_ALERT_ENABLED=true UI_BAKERY_CREDITS_ALERT_EMAIL_ENABLED=true UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT=20 ``` For custom HTML templates over SMTP, configure: ``` UI_BAKERY_MAILING_PROVIDER=smtp UI_BAKERY_MAILING_TEMPLATES_MODE=custom UI_BAKERY_MAILING_EMAIL_FROM=admin@uibakery.io UI_BAKERY_MAILING_NAME_FROM=UI Bakery UI_BAKERY_SMTP_HOST=sandbox.smtp.mailtrap.io UI_BAKERY_SMTP_PORT=2525 UI_BAKERY_SMTP_USERNAME= UI_BAKERY_SMTP_PASSWORD= UI_BAKERY_SMTP_ENCRYPTION=tls ``` For local testing, Mailtrap can be used as the SMTP server. In that case, the email recipient is still the Workspace admin email, but the message is captured in the Mailtrap inbox and is not delivered to the real mailbox. #### Email template customization The low-credit email subject and template can be customized with: ``` UI_BAKERY_MAILING_CREDITS_LOW_SUBJECT=UI Bakery usage credits are low UI_BAKERY_MAILING_CREDITS_LOW_TEMPLATE=

Low credits for organizationName

Hello userName, organizationSlug has availableCredits usage credits left from lastTopUpTotalCredits. Remaining: percentageRemaining%.

``` Available template variables:
VariableDescription
userNameAdmin display name or email.
userEmailAdmin email address.
organizationNameWorkspace display name.
organizationSlugWorkspace slug.
availableCreditsRemaining usage credits.
lastTopUpTotalCreditsLatest top-up/current balance total in usage credits.
percentageRemainingRemaining percentage.
Template substitution is plain string replacement. Use `userName`, `organizationName`, etc., directly in the template. Do not use `{{ userName }}` syntax for the SMTP custom template. Example rendered template: ```

Low credits for Acme

Hello Jane Admin, acme has 9.5 usage credits left from 250.0. Remaining: 3.8%.

``` ### Sending both email and webhook Email and webhook can be enabled together: ``` UI_BAKERY_CREDITS_ALERT_ENABLED=true UI_BAKERY_CREDITS_ALERT_EMAIL_ENABLED=true UI_BAKERY_CREDITS_ALERT_WEBHOOK_URL=https://example.com/credits-alert-webhook UI_BAKERY_CREDITS_ALERT_THRESHOLD_CREDITS=10 UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT=20 ``` When the threshold is reached, UI Bakery sends an email to Workspace admins and also posts the webhook payload. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.uibakery.io/build-with-ai/usage-credits-monitoring.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.