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 <UI_BAKERY_INSTANCE_API_TOKEN>

Example:

curl -i https://<your-instance-host>/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:

{
  "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:

organizationId	Workspace view ID.
organizationSlug	Workspace slug from the request.
availableCredits	Remaining UI Bakery usage credits.
lastTopUpTotalCredits	Total usage credits from the latest top-up/current balance period.
percentageRemaining	Remaining percentage, calculated as availableCredits / lastTopUpTotalCredits * 100, rounded to 2 decimals. May be null if the total is missing or zero.
billingDisabled	true 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

Variable	Default	Description
UI_BAKERY_CREDITS_ALERT_ENABLED	false	Enables or disables the scheduled low-credit alert job.
UI_BAKERY_CREDITS_ALERT_THRESHOLD_CREDITS	-1	Absolute usage credits threshold. -1 disables this threshold.
UI_BAKERY_CREDITS_ALERT_THRESHOLD_PERCENT	-1	Percentage remaining threshold. -1 disables this threshold.
UI_BAKERY_CREDITS_ALERT_EMAIL_ENABLED	true	Enables email delivery to organization admins.
UI_BAKERY_CREDITS_ALERT_WEBHOOK_URL	empty	Optional webhook URL for alert delivery.
UI_BAKERY_CREDITS_ALERT_COOLDOWN_HOURS	24	Per-organization cooldown after a successful alert. Prevents repeated alerts while credits remain low.
UI_BAKERY_CREDITS_ALERT_CRON	0 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:

{
  "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=[e-mail]
UI_BAKERY_MAILING_NAME_FROM=UI Bakery

UI_BAKERY_SMTP_HOST=sandbox.smtp.mailtrap.io
UI_BAKERY_SMTP_PORT=2525
UI_BAKERY_SMTP_USERNAME=<smtp-username>
UI_BAKERY_SMTP_PASSWORD=<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=<h2>Low credits for organizationName</h2><p>Hello userName, organizationSlug has availableCredits usage credits left from lastTopUpTotalCredits. Remaining: percentageRemaining%.</p>

Available template variables:

Variable	Description
userName	Admin display name or email.
userEmail	Admin email address.
organizationName	Workspace display name.
organizationSlug	Workspace slug.
availableCredits	Remaining usage credits.
lastTopUpTotalCredits	Latest top-up/current balance total in usage credits.
percentageRemaining	Remaining 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:

<h2>Low credits for Acme</h2>
<p>Hello Jane Admin, acme has 9.5 usage credits left from 250.0. Remaining: 3.8%.</p>

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.