Budget Alerts - Xerotier

Overview

Budget alerts monitor your project's token spending against configurable thresholds. When spending reaches a threshold percentage of your budget, Xerotier sends a notification via your configured channels (email or webhook). Each threshold triggers only once per billing period.

API Endpoints

Method	Endpoint	Description
GET	/api/billing/budgets	List all budget alerts for the project.
POST	/api/billing/budgets	Create a new budget alert.
GET	/api/billing/budgets/:budgetId	Get budget alert details.
PUT	/api/billing/budgets/:budgetId	Update a budget alert.
DELETE	/api/billing/budgets/:budgetId	Delete a budget alert and its history.
GET	/api/billing/budgets/:budgetId/history	Get alert history (query: `?limit=`, default 50, max 100).
POST	/api/billing/budgets/check	Manually trigger a budget check for the project.

Create a Budget Alert

curl

                    curl -X POST https://xerotier.ai/api/billing/budgets \
  -H "Authorization: Bearer xero_my-project_abc123" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: your-csrf-token" \
  -d '{
    "name": "Monthly API Budget",
    "budget_amount": 10000,
    "thresholds": [50, 75, 90, 100],
    "alert_channels": ["email", "webhook"],
    "webhook_url": "https://hooks.example.com/budget-alert"
  }'
                

The budget_amount is specified in cents. A value of 10000 represents $100.00.

Python

                    import requests

headers = {
    "Authorization": "Bearer xero_my-project_abc123",
    "Content-Type": "application/json",
    "X-CSRF-Token": "your-csrf-token"
}
response = requests.post(
    "https://xerotier.ai/api/billing/budgets",
    headers=headers,
    json={
        "name": "Monthly API Budget",
        "budget_amount": 10000,
        "thresholds": [50, 75, 90, 100],
        "alert_channels": ["email", "webhook"],
        "webhook_url": "https://hooks.example.com/budget-alert"
    }
)
print(response.json())
                

Node.js

                    const response = await fetch(
    "https://xerotier.ai/api/billing/budgets",
    {
        method: "POST",
        headers: {
            "Authorization": "Bearer xero_my-project_abc123",
            "Content-Type": "application/json",
            "X-CSRF-Token": "your-csrf-token"
        },
        body: JSON.stringify({
            name: "Monthly API Budget",
            budget_amount: 10000,
            thresholds: [50, 75, 90, 100],
            alert_channels: ["email", "webhook"],
            webhook_url: "https://hooks.example.com/budget-alert"
        })
    }
);
const data = await response.json();
console.log(data);
                

Update a Budget Alert

All fields are optional in an update request. Only provided fields are changed.

curl

                    curl -X PUT https://xerotier.ai/api/billing/budgets/budget-uuid \
  -H "Authorization: Bearer xero_my-project_abc123" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: your-csrf-token" \
  -d '{
    "budget_amount": 20000,
    "is_enabled": true
  }'
                

Thresholds

Thresholds are percentage values (1-100) that trigger notifications when your spending reaches that percentage of the budget. Common configurations:

Configuration	Thresholds	Use Case
Standard	[50, 75, 90, 100]	Gradual warnings as spending increases.
Conservative	[25, 50, 75, 90, 100]	Early warning for tight budgets.
Simple	[80, 100]	Alert only when nearing or at the limit.

Each threshold triggers only once per billing period. Once a 75% threshold fires, it will not fire again until the next billing period, even if spending fluctuates around that level.

Notifications

Budget alerts support two notification channels:

Channel	Description
`email`	Email notification sent to the project owner.
`webhook`	HTTP POST to a configured URL. Requires HTTPS.

Webhook Payload

When a threshold is triggered, the webhook receives a POST request with this payload:

JSON

                    {
  "eventType": "budget.threshold_reached",
  "alertId": "uuid",
  "alertName": "Monthly API Budget",
  "projectId": "uuid",
  "projectName": "My Project",
  "threshold": 75,
  "currentSpendCents": 7500,
  "budgetAmountCents": 10000,
  "spendPercentage": 75.0,
  "timestamp": "2026-01-15T10:30:00Z"
}
                

The webhook URL must use HTTPS. HTTP URLs are rejected during budget alert creation and updates.

Alert History

Each triggered alert is recorded in the alert history with delivery status:

curl

                    curl https://xerotier.ai/api/billing/budgets/budget-uuid/history?limit=20 \
  -H "Authorization: Bearer xero_my-project_abc123"
                

Python

                    import requests

headers = {"Authorization": "Bearer xero_my-project_abc123"}
response = requests.get(
    "https://xerotier.ai/api/billing/budgets/budget-uuid/history",
    headers=headers,
    params={"limit": 20}
)
for record in response.json():
    print(f"Threshold {record['threshold']}% at {record['notifiedAt']}")
                

Node.js

                    const response = await fetch(
    "https://xerotier.ai/api/billing/budgets/budget-uuid/history?limit=20",
    {
        headers: { "Authorization": "Bearer xero_my-project_abc123" }
    }
);
const history = await response.json();
history.forEach(record => {
    console.log(`Threshold ${record.threshold}% at ${record.notifiedAt}`);
});
                

History Record Fields

Field	Description
`threshold`	The percentage threshold that triggered (e.g., 75).
`spendAtAlert`	Spend in cents when the alert triggered.
`budgetAtAlert`	Budget amount in cents when the alert triggered.
`notifiedAt`	Timestamp of the notification.
`notificationChannel`	Channel used (email or webhook).
`deliverySuccess`	Whether the notification was delivered successfully.
`errorMessage`	Error details if delivery failed (null on success).

Billing Periods

Budget alerts operate on monthly billing periods. At the start of each new month, the system automatically resets:

notifiedThresholds -- Cleared so all thresholds can fire again.
currentSpend -- Reset to zero.
periodStart / periodEnd -- Updated to the new month.

Current spend is calculated from usage events for the current billing period. You can trigger a manual recalculation using the POST /api/billing/budgets/check endpoint.