Usage & metering

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 cadenzalabs 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

Field	Meaning
`window_days`	The trailing window the numbers cover.
`total_calls`	Every metered call in the window.
`by_route`	Calls per endpoint, e.g. `sessions.step`, `anticipators.protect`.
`sessions_opened`	`sessions.create` calls.
`steps_taken`	`step` + `perceive` calls.
`anticipators_opened`	`anticipators.create` calls.
`protects_checked`	`anticipators.protect` calls.
`sessions_touched`	Distinct session ids seen.
`anticipators_touched`	Distinct anticipator ids seen.
`first_used` / `last_used`	First/last metered call in the window (or `null`).

What counts, and what doesn’t

Every gated call is metered

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

Open + read routes are not metered

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

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.

Building deep

Patterns, rate limits, and error handling for production.

SDK reference

Full method and type reference.

Introduction

Configure

Using the CLI

Megan

Reference

From the CLI

From the SDK

The rollup fields

What counts, and what doesn’t

Where the data lives

Next

Building deep

SDK reference

​From the CLI

​From the SDK

​The rollup fields

​What counts, and what doesn’t

​Where the data lives

​Next

Building deep

SDK reference

From the CLI

From the SDK

The rollup fields

What counts, and what doesn’t

Where the data lives

Next