How do I track token usage in OpenHands?

Rius records input and output tokens, cache reads and writes, and cost on every OpenHands model call once you set three OTLP environment variables. You add no plugin and no code to your script. Token data comes through in full for Claude and GPT-4o in SDK scripts. OpenAI Responses API models and the web app’s streamed calls report no tokens.

How it works

The OpenHands Software Agent SDK traces every conversation with OpenTelemetry. When it finds the OTEL variables, it sends plain OTLP to the endpoint you set, so pointing it at Rius needs no extra package.

Rius turns each conversation into one trace. The span for each model call, named litellm.completion, carries:

• the model
• input and output tokens
• cache reads and writes
• cost
• the prompt and the answer

Rius computes the cost from the model and the token counts. It is a list-price estimate in US dollars, not a billed amount.

One example run of a Claude Haiku 4.5 task made four model calls with 31,091 input tokens, 966 output tokens and $0.0175 in all. Each agent.step groups its model call and tool call, so you can see which step spent the tokens.

OpenHands always sends prompts and output. There is no per-folder opt-in as with the coding-agent plugin. See Coding agents for how the agents compare.

Set it up

1. Install the OpenHands SDK. It needs Python 3.12 or newer.

   python3.12 -m venv .venv
   .venv/bin/pip install openhands-sdk openhands-tools

2. In the Rius console, open Settings → API keys and create a key with the Send telemetry scope. The key is shown once.

3. Set the three environment variables in the process that runs your agent:

   export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.eu.console.rius-glassflow.com/v1/traces
   export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
   export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20ri_..."

   Get the details exactly right, because a wrong value means Rius never sees the spans:

   • Use http/protobuf, because the exporter defaults to gRPC.
   • Write the full /v1/traces path.
   • Write the space after Bearer as %20.
   • Unset any LMNR_* variable. It takes precedence over the OTEL settings.

4. Run your script as usual. Tracing turns on by itself, and the conversation appears in the trace list within a few seconds. Pass observability_metadata={"agent.name": "fib-writer"} when you create the Conversation to name the agent.

5. Open a conversation and click a litellm.completion span to see that call’s tokens and cost.

6. To see token use per developer, pass user_id when you create the Conversation. Without it, conversations land in the anonymous row on the Users page.

If you run the OpenHands web app in Docker, put the three values in OH_AGENT_SERVER_ENV on the app container. The sandbox does not receive OTEL_* variables set directly on it. The OpenHands guide has the full setup, including OpenHands Enterprise.

What you get

• Tokens and cost per model call, with cache reads and writes, on the span for that call.
• Totals per conversation, because the whole conversation is one trace, so you can see which conversation or step used the most.
• Usage over time in the Usage and cost view, broken down by model and agent.
• Per-developer figures on the Users page when you pass user_id.
• Tool calls (terminal, file_editor, finish) in the same trace, so you can tie token use to what the agent did.
• Context window alerts. Rius reads the token counts on each model call to flag a run whose context is nearly full.

What OpenHands does not report:

• OpenAI Responses API models (GPT-4.1, GPT-5) have no token data in SDK scripts.
• The web app’s streamed calls have the prompt and answer for every model call, but no tokens or cost.
• OpenHands Cloud cannot send to Rius, because it takes no custom environment variables.

Rius computes cost only from token counts and a known model, so a call without tokens has no cost.

When something else fits

• If you want token and cost data for your own Claude Code sessions, or per developer across a team, the plugin route in Track Claude Code usage and cost across a team fits better.
• If your OpenHands runs use GPT-5 or the web app’s streamed calls, Rius shows the calls and tool use but cannot show tokens for them.

Related