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

# Usage tallies

> Your per-endpoint API usage — how many calls, when, against your key.

```python theme={null}
mc.usage.tallies()                                                # all-time
mc.usage.tallies(start="2026-05-01", end="2026-05-31")            # bounded range
```

## Parameters

<ParamField path="start" type="str">
  ISO date (`"YYYY-MM-DD"`). Inclusive. Omit for no lower bound.
</ParamField>

<ParamField path="end" type="str">
  ISO date. Inclusive. Omit for no upper bound.
</ParamField>

<ParamField path="format" type="str" default="&#x22;models&#x22;">
  `"models"` returns a typed `UsageResponse`; other values pass through to the
  underlying serializer.
</ParamField>

## Response shape

```python theme={null}
res = mc.usage.tallies(start="2026-05-01", end="2026-05-31")
res.to_dicts()
# [
#   {"endpoint": "v2/enrich", "count": 1247},
#   {"endpoint": "v2/resolve", "count": 318},
#   ...
# ]

res.to_df()         # pandas DataFrame   (needs [pandas])
res.to_csv("usage.csv")
res.to_table()      # pretty terminal table   (needs [table])
```

The exact response shape is server-defined; the SDK surfaces whatever
list-of-rows the server returns. Use `to_dicts()` for the raw shape,
`to_df()` for analysis.

## Common patterns

**Post-call audit** — confirm a specific call actually billed:

```python theme={null}
res = mc.usage.tallies(start="2026-06-02", end="2026-06-02")
for row in res.to_dicts():
    print(row)
```

**Monitoring feed** — periodically poll for use in dashboards / alerts:

```python theme={null}
import time

while True:
    res = mc.usage.tallies(start=today_iso(), end=today_iso())
    send_to_monitoring(res.to_dicts())
    time.sleep(3600)
```