Kimi Usage - Home Assistant Integration

A custom Home Assistant integration that monitors your Kimi Code subscription usage: how much of your rolling quota you've spent, how many requests are left in the current rate window, and when each one resets.

Authentication is a plain API key from the Kimi Code Console - no OAuth.

Sensors

Quota (refreshes every 7 days from your subscription date)

Sensor	Description
Quota Usage	Percentage of the quota consumed
Quota Usage Pace	Percentage points ahead of an even burn rate. Positive means you're spending faster than the reset clock; negative means you're comfortably under
Quota Used	Requests consumed this period
Quota Remaining	Requests left before the reset
Quota Limit	Total requests for your tier
Quota Reset Time	When the quota refreshes
API Error	1 while the last poll failed, 0 otherwise. Useful as an alert trigger

Rate windows (dynamic)

Kimi also enforces a rolling rate window - currently 5 hours - on top of the quota. Each window in the API response produces three sensors, created automatically:

• 5 Hour Limit Usage - percentage of the window consumed
• 5 Hour Limit Remaining - requests left in the window
• 5 Hour Limit Reset Time - when the window rolls over

All three carry limit, used, remaining, percent, resets_at, duration and time_unit as attributes. If Kimi adds another window, its sensors appear with no integration update; a window that disappears leaves its sensors unavailable, and recorder history is preserved.

Installation

Manual

1. Copy custom_components/hass_kimi_usage/ into your Home Assistant custom_components/ directory
2. Restart Home Assistant
3. Settings -> Devices & Services -> Add Integration -> "Kimi Usage"

deploy.sh automates the copy:

HASS_CONFIG_DIR=/path/to/your/hass-config ./deploy.sh

HACS

The repository is hosted on a self-hosted Gitea instance, and HACS installs from GitHub only - so HACS installation works only if the repo is mirrored to GitHub. hacs.json is in place for when that happens.

Setup

1. Open the Kimi Code Console
2. Click Create API Key, give it a name, and copy the key immediately - it is shown only once
3. Paste it into the Home Assistant config flow

The key is verified against the usage API before the entry is created, so a typo surfaces straight away instead of as a broken entity.

You may optionally set an account name. It only affects the device and entity names, so several Kimi accounts can be told apart in one Home Assistant instance.

Adding the same key twice is refused. Note that all API keys on an account share one quota, so there's no benefit to adding several keys from the same account - they would report identical numbers.

If a key is revoked or deleted, the next poll fails with a 401 and Home Assistant prompts you to enter a new one.

Options

• Update interval - how often to poll (default 300 seconds, min 60, max 3600)

Keep this reasonably high. Polling is itself a request against your rolling 5-hour window, so a 60-second interval spends 300 requests per window just on monitoring. At the default of 300 seconds it costs 60.

Dashboard

A ready-made dashboard is in dashboards/kimi_usage.yaml:

1. Settings -> Dashboards -> Add Dashboard
2. Three-dot menu -> "Edit Dashboard"
3. Three-dot menu again -> "Raw configuration editor"
4. Paste the file contents and save

Entity ids in the file assume the default device name; adjust them if you set an account name.

Checking the raw API

The integration reads a single endpoint. To see exactly what your account returns:

curl -s -H "Authorization: Bearer $KIMI_API_KEY" \
  https://api.kimi.com/coding/v1/usages | jq

{
  "usage": {
    "limit": "2048",
    "used": "214",
    "remaining": "1834",
    "resetTime": "2026-01-09T15:23:13.716839300Z"
  },
  "limits": [
    {
      "window": { "duration": 300, "timeUnit": "TIME_UNIT_MINUTE" },
      "detail": {
        "limit": "200",
        "used": "139",
        "remaining": "61",
        "resetTime": "2026-01-06T13:33:02.717479433Z"
      }
    }
  ]
}

Counts arrive as strings and percentages aren't provided - parser.py normalises both. If your payload differs from the above, parser.py is the only file that needs changing, and it has no Home Assistant imports so you can test it directly.

Set the integration's log level to debug to see each raw payload:

logger:
  logs:
    custom_components.hass_kimi_usage: debug

Development

python3 -m venv .venv
.venv/bin/pip install pytest ruff black isort
.venv/bin/python -m pytest tests/

The parser tests need no Home Assistant install.

Pre-commit hook

pip install pre-commit
pre-commit install

Runs black, isort, ruff and assorted file checks before each commit.

Credits

Structure and approach adapted from trickv/hass-claude-usage, which does the same job for Anthropic's Claude subscription.

License

MIT License - see LICENSE.