# Ліміти використання

> ccam usage показує 5-годинні й тижневі ліміти всіх облікових записів одночасно, а ccam statusline виводить назву облікового запису та використання в Claude Code.

Source: https://ccam.dev/uk/features/usage/ · Updated 2026-10-19

`ccam usage` показує, яку частку 5-годинного та тижневого лімітів використав кожен обліковий запис, і час до скидання кожного вікна. Використовуйте цю команду перед початком довгого завдання або коли Claude Code попереджає, що ліміт близько, щоб побачити, в якого облікового запису ще є запас. `ccam statusline` — це команда рядка стану для Claude Code: вона показує назву облікового запису й використання всередині Claude Code і зберігає числа для `ccam usage`.

## Використання

```sh
ccam usage                  # every account, once
ccam u                      # the same, shorter
ccam usage --watch          # redraw every 60 seconds until Ctrl+C
ccam usage --watch=10       # redraw every 10 seconds
ccam usage -v               # add per-model weekly limits and the data source
ccam usage --json           # machine-readable, one object per account
ccam usage --source cache   # saved numbers only, no network
ccam usage --refresh        # also renew expired logins of accounts not running
ccam statusline install     # set the status line in every account's settings.json
```

```console
$ ccam usage
 Account     5-hour        Resets    Weekly        Resets    As of
 1 personal  ░░░░░░░░   0% -         ██████░░  70% 2d 16h    9h 36m ago (cached)
 2 work      ██░░░░░░  24% 2h 29m    ███░░░░░  41% 3d 11h    just now (cached)
 3 side      login expired, run `ccam side` once to refresh
→ Most headroom: personal   (open it with ccam next --auto)
```

У терміналі таблиця з'являється одразу з `fetching…` у кожному рядку, і кожен рядок перемальовується, щойно відповідає його обліковий запис. `As of` показує давність чисел; `(cached)` означає, що вони взяті зі збереженого файлу, а не з кінцевої точки. Останній рядок називає обліковий запис із найменшим 5-годинним використанням нижче 100% і з'являється лише тоді, коли у вас більше одного облікового запису. Обліковий запис без входу показує `not logged in → ccam login <name>`, а обліковий запис із ключем API — `no limits (API)`.

Після `ccam statusline install` Claude Code показує рядок на кшталт `[work] · Opus · 5h 24% · 7d 41%`.

## Параметри

| Параметр | Дія | За замовчуванням |
| --- | --- | --- |
| `--json` | Вивести звіти у форматі JSON: `name`, `slot`, `status`, `limits`, `source`, `at`, `error` | вимкнено |
| `--watch[=N]` | Перемальовувати кожні `N` секунд, доки ви не натиснете Ctrl+C. Сам `--watch` або значення 0 чи менше означає 60 | вимкнено |
| `-v`, `--verbose` | Показувати тижневі ліміти для окремих моделей і рядок `source:` (`live`, `cache` або `statusline`) | вимкнено |
| `--no-cache` | Ігнорувати 60-секундний кеш і знову запитати кінцеву точку | вимкнено |
| `--source live\|cache` | `cache` ніколи не запитує кінцеву точку й показує лише збережені числа; `live` — поведінка за замовчуванням | live |
| `--refresh` | Оновлювати прострочені токени доступу лише для облікових записів, які не запущено | вимкнено |
| `--dry-run` | Приймається: `ccam usage` не змінює нічого, крім власного кешу. Відхиляється разом із `--refresh`: `--dry-run cannot be combined with --refresh, which rewrites login tokens` | вимкнено |

Будь-яке інше значення `--source` завершується помилкою `--source must be live or cache`. `ccam usage` не приймає аргументів.

`ccam statusline` читає JSON рядка стану Claude Code зі стандартного введення. Його єдиний параметр — `--wrap <command>`: наявна команда рядка стану, до першого рядка виводу якої додається назва облікового запису. `ccam statusline install` не має параметрів. Обидві команди відхиляють `--dry-run` з повідомленням `` --dry-run is not supported by `ccam statusline`; nothing was changed ``.

## Як це працює

Числа надходять із двох джерел: незадокументованої кінцевої точки використання Anthropic, `GET https://api.anthropic.com/api/oauth/usage`, яку викликають із власним входом кожного облікового запису, і значень, які Claude Code передає своїй команді рядка стану. Усе це міститься в `internal/usage`.

1. `cli.usageCmd` завантажує `config.toml` і будує по одному `usage.Account` на обліковий запис: його теку `~/.local/share/ccam/profiles/<name>/`, теку сеансів (щоб побачити, чи він запущений) і чи імпортовано його на місці.
2. `Fetcher.FetchAll` запускає по одній горутині на обліковий запис. Усі вони використовують один `http.Client`, тож з'єднання з кінцевою точкою використовуються повторно. Встановлення з'єднання може тривати 2 с, а кожен обліковий запис загалом має 3 с. Клієнт не переходить за переспрямуваннями, бо переспрямування надіслало б токен деінде, і читає не більше 1 МБ відповіді.
3. Щойно кожен обліковий запис завершує, його рядок перемальовується. Обліковий запис, який зазнає невдачі або не відповідає вчасно, переходить на збережені числа, тож один повільний обліковий запис ніколи не затримує інших.

Кожен обліковий запис звертається до кінцевої точки у власній горутині; той, що перевищує час очікування, натомість показує збережені числа.

`personal` і `work` відповідають вчасно й показують актуальні числа. `side` відповідає довше за 3 с, тож `fallback()` читає два його файли кешу й використовує той, що був записаний пізніше. `usage.Table()` малює рядки, а `usage.Best()` вибирає обліковий запис, названий в останньому рядку.

Для одного облікового запису `Fetcher.Fetch` виконує такі перевірки по черзі:

1. З `--source cache` він одразу переходить до `fallback()`.
2. Якщо не задано `--no-cache`, актуальний результат у `~/.local/state/ccam/usage/<name>.json`, молодший за 60 секунд (`CacheTTL`), повертається як є. Два запуски `ccam usage` поспіль коштують один запит на обліковий запис.
3. `readCredentials()` читає `.credentials.json` (або в'язку ключів macOS), не змінюючи його, і декодується лише ключ `claudeAiOauth`. Відсутність входу за підпискою означає `not logged in` або `no limits (API)`, коли `.claude.json` містить ключ API.
4. Прострочений токен доступу не використовується. Без `--refresh` обліковий запис показує свої збережені числа, позначені як прострочені.
5. Інакше ccam викликає кінцеву точку. 401 або 403 вважається простроченим входом, будь-який інший статус або тіло, яке не вдається прочитати, вважається помилкою, і в обох випадках використовуються збережені числа.
6. Коректна відповідь записується до `<name>.json` разом із часом вимірювання.

`fallback()` читає і `<name>.json`, і `<name>.statusline.json` та залишає новіший. Перш ніж показати збережені числа, він перевіряє час скидання кожного вікна: вікно, яке скинулося після збереження чисел, показує 0%, бо старий відсоток уже не актуальний. Саме тому `personal` вище показує `0%` без часу скидання.

Кінцева точка має два формати відповіді. Новіший містить масив `limits` із записами `session` (5-годинний), `weekly_all` і `weekly_scoped` (для окремих моделей). Старіший містить об'єкти `five_hour`, `seven_day`, `seven_day_opus` і `seven_day_sonnet`. `ParseLive` читає обидва: масив `limits` має пріоритет, а старі об'єкти доповнюють те, чого він не охоплює. Тіло без жодних лімітів вважається зміною формату, про яку повідомляє `ccam doctor`.

### Оновлення токенів

Токени оновлення ротуються: оновлення видає новий токен оновлення й робить старий недійсним. Якби ccam оновив вхід, поки Claude Code працює від імені того самого облікового запису, той сеанс було б виведено із системи. Тому `ccam usage` читає токени й ніколи їх не записує, якщо ви не передасте `--refresh`. Тоді `Fetcher.refresh`:

1. відхиляє облікові записи, зареєстровані на місці через `ccam import`, бо звичайний `claude` може використовувати цей вхід без відома ccam;
2. відхиляє входи, збережені у в'язці ключів macOS;
3. бере файл блокування `$XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock` (у `~/.local/state/ccam/locks/`, коли цю змінну не задано), тож два процеси ccam ніколи не оновлюють той самий токен двічі;
4. під блокуванням відмовляє, якщо запущено сеанс облікового запису, і пропускає запит, якщо інший процес уже оновив токен;
5. надсилає токен оновлення до кінцевої точки токенів і записує нові токени назад у `.credentials.json` через `fsutil.AtomicWrite`, зберігаючи всі інші ключі у файлі.

### Збирач рядка стану

Claude Code запускає команду рядка стану й передає їй через конвеєр документ JSON. ccam читає з нього назву моделі та `rate_limits`:

1. `runStatusline` визначає обліковий запис за `CCAM_PROFILE`, яку ccam задає під час запуску Claude Code, або ж зіставляючи `CLAUDE_CONFIG_DIR` з теками облікових записів.
2. `ParseStatusLine` читає `rate_limits.five_hour` і `rate_limits.seven_day`. Для облікових записів із ключем API або до першої відповіді в сеансі JSON не містить лімітів; тоді нічого не зберігається.
3. `SaveStatusLine` записує `~/.local/state/ccam/usage/<name>.statusline.json`. `ccam usage` використовує цей файл, коли кінцева точка не відповідає.
4. ccam виводить `[name] · model · 5h N% · 7d N%`. З `--wrap` він запускає вашу команду через `sh -c` з тим самим введенням і натомість виводить `[name]`, а за ним перший рядок команди.

Обгорнута команда має 2 секунди. Після цього її примусово завершують, і рядок показує лише назву облікового запису, тож повільна команда не може заблокувати рядок стану Claude Code.

`ccam statusline install` записує `statusLine` у `settings.json` кожного облікового запису. Коли обліковий запис уже має команду рядка стану, ccam зберігає її як `--wrap '<old command>'`. `settings.json`, спільний через групу, записується один раз через своє посилання, тож його отримує кожен обліковий запис групи. Повторний запуск виводить `(already set)` для файлів, які вже використовують ccam.

## Безпека та граничні випадки

- `ccam usage` ніколи не змінює файл токенів, якщо ви не передасте `--refresh`. Коли вхід прострочено, запустіть обліковий запис один раз через `ccam <name>`, і Claude Code оновить його.
- `--refresh` ніколи не чіпає запущені облікові записи, імпортовані облікові записи чи входи у в'язці ключів. Відхилене оновлення показує збережені числа й причину.
- Кінцева точка використання не задокументована публічно й може змінитися. Коли це станеться, ви все одно бачитимете збережені числа, а `ccam doctor` повідомить про зміну формату.
- Якщо збережених чисел немає й відповіді немає, рядок показує `lookup failed:` і причину, наприклад `no saved usage` з `--source cache`.
- Файли кешу містять лише відсотки й час скидання, але ніколи не токени.

## Пов'язані сторінки

- [Ліміти використання та перемикання облікових записів](https://ccam.dev/uk/docs/usage-limits.md)
- [Перемикання на наступний обліковий запис](https://ccam.dev/uk/features/next.md)
- [Робота з лімітами використання](https://ccam.dev/uk/guides/usage-limit-workflow.md)
- [Команди](https://ccam.dev/uk/docs/commands.md)