# Understanding your usage

Where your credits went, call by call, what each entry in your usage history means, and how to pull a month into a spreadsheet.

Every credit that comes into or goes out of your account is one entry in your usage history: each call charged, refused or refunded, each period's allowance and each pack. Read it on the account page, with `GET /v1/me/usage` and `GET /v1/me/usage/entries`, or by asking Kelly. Both reads cost 0 credits: looking at your balance never spends it.

## Credits and AI tokens

[Credits](/glossary#credit) are what you pay with. AI tokens are what a model reads and writes to compose an answer. An answer's entry carries both: the credits it cost and, under `ai`, the model, the model calls and the tokens it used. Data reads, calculations and Kelly Wire use no model, so their `ai` is null. Kelly never shows what the tokens cost in dollars; you pay in credits only.

## What each entry is

| `kind` | Credits | What happened |
| --- | --- | --- |
| `charge` | minus | A call spent credits: from the period's allowance, then from packs (`from_allowance`, `from_packs`). |
| `refused` | 0 | A call was refused because the allowance and packs couldn't cover it. Nothing moved. |
| `refund` | plus | A failed answer's credits came back, to where they came from. `refund_of` names the charge. A stopped answer stays charged, since the work was done. |
| `period_start` | plus | A billing period's allowance, dated at the period's first instant. |
| `pack_purchase` | plus | A credit pack you bought. |
| `pack_refund` | minus | What a refunded pack still held, taken away. |
| `pack_expiry` | minus | What an expired pack still held. |
| `earlier` | minus | Usage from before the history began, one entry per day and source, from the daily totals. |

`kind`, `operation`, `result` and `source.kind` are open lists: accept values you don't know. Each entry also carries `allowance_left_after` and, where packs were touched, `packs_left_after`, so you can see the balance move.

## In an AI app

Connect Kelly to an AI app and ask about your credits: the `get_my_usage` tool reads the same history at no credit cost. By default it returns this period's balance and pace, your packs, credits by action and by source, and your latest entries; ask for every entry and it pages through them. In an AI app a source is its kind and ID, and a chat or project its ID only: your keys', apps', chats' and projects' names stay on askkelly.ai.

## Who sees what

The account page shows your whole account. A key or a connected app sees only its own entries, in its own mode, unless it holds the `read:usage` scope: you add it to a key on the account page (no key has it by default), and an app has to ask you for it when you connect. Entries that aren't calls, such as a period's allowance or a pack, are the whole account's, so only a reader with `read:usage` or the account page sees them.

## Filters

Both reads take the same filters: `since` (RFC 3339; the start of your current billing period by default) and `until` (RFC 3339; leave it out to read up to now), `tz` (the time zone days are counted in; your account's by default), `kind` and `operation` (repeat either for more), `source` (`site`, `wire`, `key`, `app`, or one key or app such as `key:key_…`), `project_id`, `mode` and `q` (an entry, request, answer or subject ID). `GET /v1/me/usage` adds `group_by`: `operation` (the default), `source`, `day`, `project` or `kind`. `GET /v1/me/usage/entries` adds `limit` (up to 100) and `cursor`, and returns entries newest first.

```bash Terminal
curl "https://api.askkelly.ai/v1/me/usage?group_by=source" \
  -H "Authorization: Bearer $KELLY_API_KEY"
```

## Pull a month into a spreadsheet

Page through a month's entries and write one CSV row per entry. The sample needs Python 3 and a key with `read:usage`.

```python usage_csv.py
import csv, json, os, sys, urllib.parse, urllib.request

BASE = "https://api.askkelly.ai/v1/me/usage/entries"
params = {"since": "2026-10-01T00:00:00Z", "until": "2026-11-01T00:00:00Z", "limit": 100}
headers = {"Authorization": f"Bearer {os.environ['KELLY_API_KEY']}"}
out = csv.writer(sys.stdout)
out.writerow(["at", "kind", "operation", "source", "credits", "allowance_left_after", "result"])
while True:
    req = urllib.request.Request(f"{BASE}?{urllib.parse.urlencode(params)}", headers=headers)
    page = json.load(urllib.request.urlopen(req))
    for e in page["data"]:
        source = (e["source"] or {}).get("name", "")
        row = [e["at"], e["kind"], e["operation"] or "", source, e["credits"], e["allowance_left_after"], e["result"] or ""]
        # a cell a spreadsheet would read as a formula is written as text
        out.writerow(["'" + c if isinstance(c, str) and c[:1] in "=+-@" else c for c in row])
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]
```

Run it with `python usage_csv.py > october.csv`. A cursor works only with the filters it came with, so keep `params` as they were when you add the cursor.

---

Last updated October 19, 2026

Support: support@askkelly.ai · Security and disclosure: https://docs.askkelly.ai/security

Data is the edge. Odds are information, not advice · 21+ · Get help
