Skip to main content

llm-usage-meter

Check your remaining LLM credits and quota across providers — from the terminal, in one command.

  • Zero dependencies. Pure Python stdlib on Linux/macOS; on Windows pip auto-installs only the tiny windows-curses shim for the dashboard.
  • Never costs credits. Only free endpoints are used: billing/balance APIs, the free count_tokens probe, and model lists. No inference calls, ever.
  • General & extensible. Add a provider in ~30 lines.
  ● Anthropic
      Requests left / min       48 / 50          █████████████████████░  96%
      Input tokens left / min   39,214 / 40,000  ██████████████████████  98%
      live rate-limit headers via free count_tokens probe; no credits consumed

  ● OpenRouter
      Credits left     $12.06 / $25.00  ███████████░░░░░░░░░░░  48%
      Used (lifetime)  $12.94
      prepaid balance from /credits

  ● DeepSeek
      Usable         yes
      Balance (USD)  $4.87
      account balance from /user/balance

Meters are color-coded (green > 50%, yellow > 20%, red below) and llm-usage-meter -w 60 turns this into a live full-screen dashboard that refreshes every 60 seconds.

Install

From PyPI:

pip install llm-usage-meter    # recommended
# or
pipx install llm-usage-meter     # isolated, CLI on your PATH

Configure

Set the environment variables for the providers you use — that's it:

Provider Env var What you get
OpenRouter OPENROUTER_API_KEY Prepaid credits remaining (real $ balance)
DeepSeek DEEPSEEK_API_KEY Account balance (real $ balance)
Anthropic ANTHROPIC_API_KEY Live per-minute rate limits remaining
Gemini GEMINI_API_KEY Key health + free quota probe (OK/rate-limited)
OpenAI OPENAI_ADMIN_KEY Month-to-date spend (org admin key required)
xAI XAI_API_KEY Key health / blocked status
Groq GROQ_API_KEY Key status + rate-limit headers when available

Providers without a key are skipped silently.

No manual file editing needed — keys are managed with the key subcommand:

llm-usage-meter key set anthropic     # prompts for the key with hidden input
llm-usage-meter key set openrouter    # (nothing echoes to screen or shell history)
llm-usage-meter key list              # show configured keys, masked: sk-ant…6789
llm-usage-meter key delete anthropic  # remove a stored key

Keys are written to ~/.config/llm-usage-meter/config.toml, which is created with chmod 600 (owner read/write only) automatically. Hidden input means the key never appears in your terminal scrollback or ~/.bash_history. Keys in the config file take priority over environment variables.

You can still edit the file by hand (llm-usage-meter --init writes a commented template) — the subcommands and manual edits coexist fine.

Interactive dashboard (default)

Just run it — in a real terminal, llm-usage-meter opens a live interactive dashboard (stdlib curses, still zero dependencies):

 llm-usage-meter  live dashboard · refreshed 3s ago · auto 60s
 ─────────────────────────────────────────────────────────────────
 ▸ ● Anthropic     key: config (sk-ant…cdef)
      Requests left / min   48 / 50   ████████████████░░  96%
   ● OpenRouter    key: env (sk-or-…9x2k)
      Credits left   $12.06 / $25.00  ████████░░░░░░░░░░  48%
   ○ Groq          no key — press a to add
 ─────────────────────────────────────────────────────────────────
 ↑↓ select   a add/edit key   d delete key   r refresh   q quit

Only providers with a configured key appear on the dashboard — it stays clean no matter how many providers llm-usage-meter supports. First launch with no keys shows a friendly empty state pointing you at a.

  • ↑/↓ (or j/k) select a provider
  • a — open the Add-provider picker (lists only providers you haven't configured), then paste the key (masked input, saved to the 600-permission config, fetches immediately)
  • e or Enter — edit the selected provider's key
  • d — delete the stored key; the provider disappears from the dashboard (with y/N confirmation)
  • r — refresh all; auto-refreshes every 60 s
  • q — quit

Fetches run in background threads, so the UI never freezes. Works on Linux, macOS, and Windows — installing from pip pulls in the small windows-curses shim automatically on Windows only.

Non-interactive contexts (pipes, scripts, cron) automatically get the classic one-shot output; force it anytime with llm-usage-meter --once.

Use

llm-usage-meter --once              # one-shot report (skip the dashboard)
llm-usage-meter -p anthropic        # one provider only
llm-usage-meter -w 60               # live dashboard, refresh every 60s
llm-usage-meter --json              # for scripts / status bars
llm-usage-meter --demo              # sample output, no network

Exit code is non-zero if any provider errored — handy for cron alerts:

llm-usage-meter --json || notify-send "LLM quota check failed"

Why some providers show different things

There is no universal "credits left" API. Each provider exposes something different, and llm-usage-meter shows the best available truth for each:

  • Prepaid balance (OpenRouter, DeepSeek): a real dollar number remaining.
  • Rate limits (Anthropic): pay-as-you-go has no "balance", so the meaningful quota is your per-minute request/token allowance, read from response headers on a free count_tokens call.
  • Spend so far (OpenAI): OpenAI exposes cost history, not a balance; llm-usage-meter shows month-to-date spend so you can compare against your budget.

Add your own provider

Subclass Provider in llm_usage_meter/providers.py:

class MyProvider(Provider):
    name = "MyProvider"
    env_key = "MYPROVIDER_API_KEY"
    config_section = "myprovider"

    def fetch(self, key):
        status, headers, data = _request(
            "https://api.myprovider.com/v1/balance",
            headers={"Authorization": f"Bearer {key}"},
        )
        if status != 200:
            return QuotaResult(self.name, error=_api_err(status, data))
        return QuotaResult(self.name, ok=True,
                           rows=[("Balance", _fmt_money(data["balance"]))])

Then add MyProvider() to the PROVIDERS list. Done.

License

MIT

Metadata

Release files for llm-usage-meter 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llm-usage-meter 0.1.1
File Size Uploaded Provenance Actions
llm_usage_meter-0.1.1.tar.gz 22.8 kB Without provenance Details for llm_usage_meter-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llm-usage-meter 0.1.1
File Interpreter ABI Platform Actions
llm_usage_meter-0.1.1-py3-none-any.whl Python 3 none any Details for llm_usage_meter-0.1.1-py3-none-any.whl

Total release size: 43.1 kB

Release files / llm_usage_meter-0.1.1.tar.gz

Download URL llm_usage_meter-0.1.1.tar.gz
Size 22.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5766c6543339b5e76b3d3274462fe0619778bf2dd615047af2902d3271d48a9a
BLAKE2b-256 checksum
How to use checksums
5bc056a21e9e4bfda281110c2979bb4892dff2efa84b2ad3225afddeb0050187
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.1

Release files / llm_usage_meter-0.1.1-py3-none-any.whl

Download URL llm_usage_meter-0.1.1-py3-none-any.whl
Size 20.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2060b5f8c4a511a78e8bab0d8d9f0d21e500b910d9950730d9af9fcc4cee245c
BLAKE2b-256 checksum
How to use checksums
66bd307cb6277af07f834fcc32329b12a3d3a6939e11ea13e3c6548d98c9809a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.1

Security for llm-usage-meter 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page