CoderHelm Docs
APIUsage

Get this month's usage

GET
/api/usage

Returns the tokens the team used this calendar month (UTC), split into new input, output, cache reads and cache writes, per feature, and against each limit the team set. When a limit is reached, endpoints that start work answer 429 with token_limit_reached until the month turns or an admin raises it.

Authorization

api_key view
headerAuthorizationBearer <token>

A team API key, made by an admin under Settings, API keys. Send it as Authorization: Bearer chk_....

Scope: view

Response Body

This month's usage.

application/json
  1. response

The team's token usage this month.

cache_hit_rate*number

Cache reads divided by all input, from 0 to 1.

Formatdouble
Example0.77
cache_read_tokens*integer

Tokens read from the prompt cache.

Formatint64
Range0 <= value
Example13100400
cache_write_tokens*integer

Tokens written to the prompt cache.

Formatint64
Range0 <= value
Example822392
counted_tokens*integer

What the older single limit counts (kept for older clients).

Formatint64
Range0 <= value
Example4310227
features*array<>

Usage per feature.

limit_counts_cache*boolean

Whether the older single limit counts cache tokens (kept for older clients).

Examplefalse
limits*array<>

Each limit that is set, in display order. Empty when none is.

limits_legacy*boolean

True when the limits were read from the older single-limit setting.

Examplefalse
max_tokens*integer

The older single limit, 0 when it isn't used (kept for older clients).

Formatint64
Range0 <= value
Example0
month*string

The month, YYYY-MM (UTC).

Example"2026-10"
new_tokens*integer

New input plus output: what the new_tokens limit counts.

Formatint64
Range0 <= value
Example4310227
tokens_in*integer

New input tokens (not from the cache).

Formatint64
Range0 <= value
Example3011022
tokens_out*integer

Output tokens.

Formatint64
Range0 <= value
Example1299205
total_runs*integer

Runs started this month.

Formatint64
Range0 <= value
Example37
total_tokens*integer

All tokens: new input, cache reads, cache writes and output.

Formatint64
Range0 <= value
Example18233019
curl -X GET 'https://api.coderhelm.com/api/usage' \  -H "Authorization: Bearer $CODERHELM_API_KEY"
{  "cache_hit_rate": 0.77,  "cache_read_tokens": 13100400,  "cache_write_tokens": 822392,  "counted_tokens": 4310227,  "features": [    {      "cache_read_tokens": 1900410,      "cache_write_tokens": 151002,      "feature": "reviewer",      "tokens_in": 301200,      "tokens_out": 57410,      "total_tokens": 2410022    }  ],  "limit_counts_cache": false,  "limits": [    {      "kind": "new_tokens",      "max": 20000000,      "used": 4310227    }  ],  "limits_legacy": false,  "max_tokens": 0,  "month": "2026-10",  "new_tokens": 4310227,  "tokens_in": 3011022,  "tokens_out": 1299205,  "total_runs": 37,  "total_tokens": 18233019}
Edit on GitHub

Retry a run POST

Starts the run's ticket again as a new run. Only a run that is `failed`, `needs_input`, `needs_outside_change`, `cancelled` or `closed` can be retried; the old run becomes `retried`, so retrying it twice is refused with `400`. Find the new run with `GET /api/runs?q=<ticket id>`.

AWS SNS alerts POST

Subscribe CoderHelm to an SNS topic with an HTTPS subscription to this address and add the topic under Alert routes in the dashboard. Every message's SNS signature is checked (signature versions 1 and 2) and the signing certificate must come from SNS. The subscription is confirmed automatically once the topic has an enabled route; messages from topics without one are accepted and ignored. A message that matches one of the route's rules becomes a run that opens a pull request.