> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-add-cookbook-tab.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation Metrics

> Retrieve cost, token usage, and cache statistics for any OpenHands conversation using a CLI tool that supports both V0 and V1 APIs.

**Source:** [`conversation-metrics/`](https://github.com/jpshackelford/oh-examples/tree/main/conversation-metrics)

`oh-metrics` is a zero-dependency CLI tool that fetches cost and token usage for an OpenHands conversation. It automatically detects whether the conversation uses the V0 or V1 API and applies the appropriate retrieval strategy.

## Installation

```bash theme={null}
git clone https://github.com/jpshackelford/oh-examples.git
cd oh-examples
pip install -e conversation-metrics/
```

Or run the script directly (Python 3.10+ required):

```bash theme={null}
chmod +x oh-examples/conversation-metrics/oh-metrics
```

## Usage

```bash theme={null}
export OH_API_KEY="your-api-key"
./oh-metrics <conversation_id>
```

## Example Output

```
────────────────────────────────────────────────────────────
Conversation: 72d40619b8534f9b9de6c3f17a71072d
Title: Fix authentication bug
API Version: V1 via V1 (events)
────────────────────────────────────────────────────────────
💰 Total Cost: $0.42 USD

📊 Token Usage:
   Prompt tokens:     245,120
   Completion tokens: 3,840
   Total tokens:      248,960

🗄️  Cache:
   Cache read:        198,400
   Cache write:       42,720

📐 Context window:    200,000
────────────────────────────────────────────────────────────
```

## JSON Output

Pass `--json` for programmatic use:

```bash theme={null}
./oh-metrics <conversation_id> --json
```

## Features

* **Auto-detects** conversation version (V0 vs V1) and uses the appropriate API
* **Graceful fallback** chain — tries multiple endpoints until one succeeds
* **JSON output** for integration with dashboards or alerting pipelines
* **API call logging** with `--verbose` for debugging
* **Zero dependencies** — uses only the Python standard library
* **Fixture-based testing** — high test coverage via recorded API responses

## Getting a Conversation ID

Conversation IDs appear in the URL when you open a conversation:

```
https://app.all-hands.dev/conversations/<conversation_id>
```

You can also retrieve them programmatically:

```bash theme={null}
curl -s https://app.all-hands.dev/api/v1/app-conversations \
  -H "X-Session-API-Key: $OH_API_KEY" | python3 -m json.tool
```

## See Also

* [Conversation Tags](/cookbook/conversation-tags) — Attach metadata to conversations for tracking and filtering