> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadenzalabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & metering

> Every megan-tk call is metered per account. Read it back from the CLI or the SDK.

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

```bash theme={null}
cadenza usage
```

```text theme={null}
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`:

```bash theme={null}
cadenza usage --days 7
```

<Note>
  `usage` requires [sign-in](/cli-setup/authentication) — it reads the account tied
  to your token.
</Note>

## From the SDK

```python theme={null}
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

| 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

<Steps>
  <Step title="Every gated call is metered">
    Opening, stepping, perceiving, inspecting, and closing sessions and
    anticipators each record exactly one usage row.
  </Step>

  <Step title="Open + read routes are not metered">
    `version` (open) and reading `usage` itself are **not** counted — checking
    your usage never inflates it.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/megantk/building-deep#rate-limits)).

<Info>
  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.
</Info>

## Next

<CardGroup cols={2}>
  <Card title="Building deep" icon="screwdriver-wrench" href="/megantk/building-deep">
    Patterns, rate limits, and error handling for production.
  </Card>

  <Card title="SDK reference" icon="book" href="/megantk/sdk-reference">
    Full method and type reference.
  </Card>
</CardGroup>