Skip to main content
Every gated megan-tk call you make is counted server-side against your account. You can read your consumption back two ways — the usage CLI command or the SDK’s tk.usage() — and both return the same per-route breakdown plus a session/anticipator rollup.

​
From the CLI

cadenza usage

megan-tk usage  last 30 day(s) · account 45d4…de98

  total calls              18
  sessions opened           2
  steps taken               5
  anticipators opened       1
  protect checks            1
  distinct sessions         2
  distinct anticipators     1
  first used   2026-07-06T20:05:54Z
  last used    2026-07-06T20:05:58Z

  by endpoint
  ┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
  ┃ route                   ┃ calls ┃
  ┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
  │ anticipators.disturbance│     3 │
  │ sessions.step           │     3 │
  │ sessions.create         │     2 │
  │ …                       │     … │
  └─────────────────────────┴───────┘
Change the trailing window with --days: 
cadenza usage --days 7
usage requires sign-in — it reads the account tied to your token.

​
From the SDK

from cadenza_cli import MeganTK

tk = MeganTK()
u = tk.usage()          # or tk.usage(days=7)

u["total_calls"]        # 18
u["by_route"]           # {'sessions.step': 3, 'sessions.create': 2, ...}
u["sessions_opened"]    # 2
u["steps_taken"]        # 5  (step + perceive)
u["last_used"]          # ISO-8601 timestamp

​
The rollup fields

FieldMeaning
window_daysThe trailing window the numbers cover.
total_callsEvery metered call in the window.
by_routeCalls per endpoint, e.g. sessions.step, anticipators.protect.
sessions_openedsessions.create calls.
steps_takenstep + perceive calls.
anticipators_openedanticipators.create calls.
protects_checkedanticipators.protect calls.
sessions_touchedDistinct session ids seen.
anticipators_touchedDistinct anticipator ids seen.
first_used / last_usedFirst/last metered call in the window (or null).

​
What counts, and what doesn’t

1

Every gated call is metered

Opening, stepping, perceiving, inspecting, and closing sessions and anticipators each record exactly one usage row.
2

Open + read routes are not metered

version (open) and reading usage itself are not counted — checking your usage never inflates it.
3

Metering never slows or fails a call

Rows are written in a background task, best-effort. If the metering write fails, your decision call still succeeds — you just miss that row.

​
Where the data lives

Usage is stored in Supabase against your account and is derived purely from your own rows — you only ever see your own numbers (the account is taken from your token, never from the request). Rate limits apply per account (see Building deep).
Running your own Cadenza API? The metering table is created by supabase/05_megantk_usage.sql, and the server needs its Supabase service_role grant on that table for both the writes and the usage read to work.

​
Next

Building deep

Patterns, rate limits, and error handling for production.

SDK reference

Full method and type reference.