Budgets and Usage

Use budgets to control spending and usage reports to understand where that spend comes from. On OpenHands Enterprise deployments with the managed LLM gateway enabled, the budget summary and conversation usage reports use different accounting sources and can show different totals.

​

Budgets

Budgets control how much an organization and its members can spend through the deployment’s managed LLM gateway. Three controls work together:

• Organization budget: A monthly cap shared by the organization.
• Default user budget: A monthly limit for members without an individual override.
• User overrides: A different monthly limit for a particular member, or an exemption from the individual limit.

A user with allowance remaining can still be blocked when the organization reaches its cap. An exemption from an individual limit does not exempt that user’s requests from the organization budget.

​

Setting the Organization Budget

1. Select the organization you want to manage and open Settings > Budgets.
2. Select Organization budget.
3. Enter the monthly spending cap.
4. Under Billing cycle resets, choose the first or fifteenth of each month. Resets occur at 00:00 UTC.
5. Configure any available alert thresholds and notification channels, then select Save changes.

The page shows spend for the current cycle and the next reset date. Usage is measured against a baseline at the start of the cycle; the gateway’s cumulative lifetime spend is not the current cycle’s spend. Changing the reset day preserves current spend and can shorten or lengthen the current cycle.

​

Setting Default User Budgets and Overrides

In Settings > Budgets, select Default budget for users, enter a monthly amount, and select Update default. Existing and new members without an individual override use this default. Lowering the default below a member’s current usage can block further requests. To change one member’s limit, select User overrides, find the member, and edit their monthly budget. Select Save to apply the override. To exempt a member from the individual limit, choose Unlimited budget for this user. The organization cap still applies. Remove an override to return the member to the default user budget. Individual limits follow the organization’s configured budget cycle. Increasing a limit can restore access if the user’s limit was the reason requests were blocked, provided the organization also has allowance remaining and the gateway has applied the change.

​

Enforcement, Resets, and Alerts

The managed gateway meters usage and makes the final decision to admit each LLM request. When the applicable organization or user limit is reached, further requests can be blocked, including requests from existing conversations. Access can resume after the next verified cycle reset or an applied budget increase. Alerts apply to the organization budget, rather than individual user limits, at configured thresholds such as 80%, 90%, and 100%. Each threshold is tracked once per cycle. Email notifications go to Admins and Owners; Slack notifications go to the configured channel. Available channels depend on the deployment’s integrations. Alerts and enforcement are separate: a missing notification does not mean requests are still allowed. Review the gateway status on the budget page if a change cannot be applied or verified. Saving a change alone does not establish that the gateway is enforcing the new limit.

​

Usage

Usage reports help administrators understand activity across the organization and help members review their own conversations. Select the organization before comparing reports.

​

Organization Usage Dashboard

Open Settings > Dashboard to review the organization’s activity, token usage, estimated spend, and breakdowns by user, model, or agent. The Overview total and model/agent breakdowns use the selected reporting window. The Users tab instead shows calendar month-to-date (MTD), year-to-date (YTD), and lifetime spend. MTD starts on the first of the calendar month, even when the budget cycle resets on the fifteenth. These figures come from OpenHands conversation records and the conversation cost ledger, rather than all requests metered by the managed gateway.

​

Your Budget

Open Settings > Your Budget to see your allocation, spend, remaining allowance, and reset date for the current budget cycle. The daily spending chart and model breakdown use conversation usage records for the selected reporting period. Recent Usage lists the six most recently updated top-level conversations and each conversation’s accumulated cost. That list is not limited to the selected period; its amounts can include earlier spend. The spend summary uses gateway accounting for the budget cycle. The available allowance also accounts for the organization’s remaining budget. These sections can differ even when they appear on the same page.

​

Spend Freshness

Budget spend can be live, stale, or unavailable. A stale value is the last successfully validated gateway snapshot; unavailable means the page cannot report a validated spend value. Check the status and observation time when investigating a difference. Unavailable spend should not be interpreted as zero.

​

Why Totals Can Differ

The budget summary and conversation usage reports measure different scopes and periods: Budget spend includes application, automation, SDK, and local Agent Canvas requests routed through the deployment’s managed gateway and attributed to the organization or user. SDK or local Agent Canvas requests without an OpenHands-managed conversation can increase budget spend without appearing in the conversation usage breakdown. Calls made directly to an external provider are outside this gateway’s budget enforcement. The organization total uses the gateway’s team counter. It can include gateway identities that are not mapped to OpenHands organization members. The budget page shows their count and cycle spend when that attribution is available, so member conversation totals may not explain all organization spend. The reporting periods can also differ. A dashboard showing the last seven days does not cover the same period as a monthly budget cycle. Gateway counters and conversation records update separately, so recent usage may appear in one view before the other. If a gateway spend read fails, the budget view can show a previously validated snapshot marked as stale, or report spend as unavailable. For example, a budget total of $0.09 and a dashboard total of $0.04 could reflect gateway requests that are absent from the conversation breakdown. The amounts alone do not establish the cause.

​

Reconciling a Difference

To investigate a difference:

1. Compare the same organization and user scope. Check the budget page for unmapped gateway identities and any spend attributed to them.
2. Check each figure’s reporting period. Dashboard windows such as 7d, 30d, and 90d are rolling; MTD follows the calendar month. Neither necessarily matches the budget cycle. Recent conversation amounts are cumulative, so adding them does not give a period total.
3. Check whether SDK or local Agent Canvas requests used the managed gateway without creating managed conversations.
4. Refresh both views after usage has been recorded, and check the budget spend status and observation time.
5. If the difference remains unexplained, contact OpenHands Support with the application and chart versions, screenshots of both views, the selected reporting period, and the time of the comparison.

​

Next Steps

• Organization Settings - Configure organization settings.
• Managing Members - Invite users and manage roles.
• Roles and Permissions - Understand permission levels.