Skip to main content

View source on GitHub

OpenHands provides usage dashboards, but organizations often want to customize them for their own needs. This recipe shows how to build your own dashboard, including per-agent usage details that help you decide which steps to optimize. The example lists conversations across one organization. Select a conversation to see how its cost and tokens are split across the main agent, sub-agent tasks, and condenser. Use the example to understand how the API data becomes a dashboard, then adapt the view to what your team wants to track. It runs using a simple HTML page and a small Python server. The dashboard sends only GET requests. It does not affect any organization settings or conversations.

Screenshots

These screenshots use made-up conversations and usage data. Filter the conversation list by search, status, and tags: Conversation list showing titles, creators, status, tags, cost, and token usage Select a conversation to inspect its agent-level usage and task timing: Conversation detail showing main-agent, sub-agent, and condenser usage, with task status and timing

How It Works

The browser displays the dashboard, and the Python server gets its data from OpenHands. The API key stays in Python; it isn’t sent to the browser. Two API calls drive the page:
  1. List conversations. UsageClient.list_conversations() in usage_dashboard.py fetches one page of conversations with their titles, user tags, creators, status, and total usage. Search and status filters are sent with this request.
  2. Read a conversation’s usage. When you select a row, UsageClient.get_usage() fetches its agent-level breakdown and task timing. index.html turns that response into the detail tables.
The endpoint paths are listed under APIs Used. Detailed usage is fetched only when you select a conversation.

Prerequisites

  • OpenHands Enterprise 0.110.0 or later, or OpenHands Cloud.
  • An API key for an Owner or Admin of the organization. Members and service accounts can’t list organization conversations or read detailed usage.
The key has all of its user’s permissions, not only read access. Keep it in an environment variable on the machine that runs the dashboard.

Run It

Open the URL, then select a conversation to see its breakdown. Use --port or PORT to change the port. The key is read only from OH_API_KEY.

Customize the Dashboard

Start with the part you want to change: For example, replace the free-text tag filter with a dropdown of your teams. Keep the field name tag and send values such as team=demo; the existing Python filter will handle them. The tag filter checks only the loaded page, because the organization list API doesn’t filter by tag. The status filter sends one execution_status value. The API accepts several statuses if you repeat the parameter, such as execution_status=running&execution_status=paused. Its reference describes a comma-separated list, but release 1.94.1 treats running,paused as one value. If you add usage calculations, keep conversation totals separate from their agent breakdown so you don’t count the same usage twice. Keep the completeness indicator visible, and treat an unknown value differently from zero.

Turn On Detailed Usage

The conversation list works with the default settings. Detailed usage is off by default, and until it is on, selecting a conversation shows:
The dashboard doesn’t change this setting. An Owner or Admin turns it on once, separately:
Set it to false to turn it off again. The change takes effect on the next request; the list and totals keep working. See Conversation Usage Access. That page calls the base URL OH_BASE_URL; this example uses OH_API_BASE.

Try It With Synthetic Data

tests/fixture_api.py serves made-up data in the same shape as the API. Use it to explore the page and try changes without a real organization or API key. Install requests with pip install requests, then use two terminals. In one terminal, start the test API from this example’s directory:
In a second terminal, start the dashboard from the same directory:
Open http://127.0.0.1:8501 to see the list. To enable detailed usage in the test API, open http://127.0.0.1:8600/__fixture/detail?enabled=1 in your browser, then return to the dashboard and select a conversation. This control changes only the test API. Use enabled=0 to turn it off again. Press Ctrl+C in each terminal when you’re finished. Run the tests from the repository root with uv run pytest conversation-usage-dashboard.

APIs Used

conversation-metrics

Cost and token totals from the command line

conversation-tags

Add the tags shown in the list

Roles and Permissions

Who can view organization conversations and usage