> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation Usage Dashboard

> Browse an organization's conversations and see each one's cost and tokens by agent, task, and condenser.

> [card] [View source on GitHub](https://github.com/OpenHands/enterprise-cookbook/tree/main/conversation-usage-dashboard)

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](https://raw.githubusercontent.com/OpenHands/enterprise-cookbook/main/conversation-usage-dashboard/images/conversation-list.png)

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](https://raw.githubusercontent.com/OpenHands/enterprise-cookbook/main/conversation-usage-dashboard/images/conversation-detail.png)

## 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`](https://github.com/OpenHands/enterprise-cookbook/blob/main/conversation-usage-dashboard/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`](https://github.com/OpenHands/enterprise-cookbook/blob/main/conversation-usage-dashboard/index.html) turns that response into the detail tables.

The endpoint paths are listed under [APIs Used](#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.

> [!WARNING]
>
> 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

```bash theme={null}
pip install requests
export OH_API_KEY=...          # Owner or Admin key
export ORG_ID=...              # the organization to show
export OH_API_BASE=https://app.all-hands.dev   # or your Enterprise URL
python usage_dashboard.py
```

```text theme={null}
Dashboard: http://127.0.0.1:8501
```

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:

| What You Want to Change | Where to Start |
| - | - |
| Columns, labels, filters, or layout | `loadList()` and `loadDetail()` in [`index.html`](https://github.com/OpenHands/enterprise-cookbook/blob/main/conversation-usage-dashboard/index.html) |
| Fields passed to the page and tag filtering | `conversation_page()` in [`usage_dashboard.py`](https://github.com/OpenHands/enterprise-cookbook/blob/main/conversation-usage-dashboard/usage_dashboard.py) |
| API requests for the list or selected conversation | `UsageClient` in [`usage_dashboard.py`](https://github.com/OpenHands/enterprise-cookbook/blob/main/conversation-usage-dashboard/usage_dashboard.py) |

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:

```text theme={null}
Detailed usage isn't available. It requires an Owner or Admin key, and an Owner or Admin must turn it on for the organization with PATCH /api/organizations/{org_id}.
```

The dashboard doesn't change this setting. An Owner or Admin turns it on once,
separately:

```bash theme={null}
curl --fail --silent --show-error -X PATCH \
  "$OH_API_BASE/api/organizations/$ORG_ID" \
  -H "Authorization: Bearer $OH_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"enable_conversation_usage_detail": true}'
```

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](https://docs.openhands.dev/openhands/usage/cloud/organizations/roles-permissions.md#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`](https://github.com/OpenHands/enterprise-cookbook/blob/main/conversation-usage-dashboard/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:

```bash theme={null}
python tests/fixture_api.py --port 8600
```

In a second terminal, start the dashboard from the same directory:

```bash theme={null}
OH_API_KEY=synthetic-test-key ORG_ID=00000000-0000-4000-8000-0000000000aa \
  OH_API_BASE=http://127.0.0.1:8600 python usage_dashboard.py
```

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

| Endpoint | Purpose |
| - | - |
| `GET /api/organizations/{org_id}/conversations` | List conversations with `page`, `per_page`, `search`, and `execution_status` |
| `GET /api/organizations/{org_id}/conversations/{conversation_id}/usage` | Usage by bucket, task calls, and completeness for one conversation |

## Related

> [card] [conversation-metrics](https://docs.openhands.dev/cookbook/conversation-metrics.md)
>
> Cost and token totals from the command line

> [card] [conversation-tags](https://docs.openhands.dev/cookbook/conversation-tags.md)
>
> Add the tags shown in the list

> [card] [Roles and Permissions](https://docs.openhands.dev/openhands/usage/cloud/organizations/roles-permissions.md)
>
> Who can view organization conversations and usage


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.