Understanding your usage
Copy page
Where your credits went, call by call, what each entry in your usage history means, and how to pull a month into a spreadsheet.
On this page
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 tokensLink to this section
Credits 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 isLink to this section
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 appLink to this section
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 whatLink to this section
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.
FiltersLink to this section
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.
curl "https://api.askkelly.ai/v1/me/usage?group_by=source" \
-H "Authorization: Bearer $KELLY_API_KEY"Pull a month into a spreadsheetLink to this section
Page through a month's entries and write one CSV row per entry. The sample needs Python 3 and a key with read:usage.
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.