Billing and Usage - mAIvn Docs

#Billing, usage, and plan limits

#Per-invocation usage

Agent.invoke(), Swarm.invoke(), and their async forms return an InvokeResponse. Its token_usage field is a JSON dictionary when the runtime reports usage. It is not a TokenUsage attribute model.

Python

from maivn import Agent

agent = Agent(name="assistant", api_key="...")
response = agent.invoke("Summarize the latest release notes")

usage = response.token_usage
if usage is not None:
    print(usage.get("input_tokens"))
    print(usage.get("output_tokens"))
    print(usage.get("total_tokens"))

Provider and runtime versions may add keys, so treat this dictionary as an extensible payload and guard optional values.

For provider-reported counts and a clearly illustrative cost calculation, see Usage and Cost. Do not treat that example's placeholder rates or model names as the live catalog.

#Aggregated billing models

The SDK exports BillingUsage, BillingPlan, BillingCurrentUsage, and nested breakdown models. These validate data obtained by an authorized application integration. They do not fetch it.

Python

from maivn import BillingUsage

usage = BillingUsage.model_validate(application_payload)
print(usage.organization_id)
print(usage.breakdown.totals.billed_tokens)

The public Client does not provide get_usage(). Do not infer a billing URL or call an undocumented HTTP helper. Returned plan fields describe the supplied payload. The supplying service is authoritative for current availability, prices, allowances, and enforcement.

#Automatic reload

Automatic reload lets an eligible organization pre-authorize a fixed-dollar reload when remaining usage reaches a selected threshold. It is off by default. The control requires a saved payment method and an environment where billing is enabled. It is unavailable while hosted billing is disabled. Confirm availability in your provisioned environment.

When the control is available, you choose:

Setting	Meaning
On or off	Whether future automatic reload attempts are allowed.
Amount	Whole US dollars requested for each reload, within the displayed limits.
Trigger	A remaining-percent or remaining-units threshold.
Period cap	Optional maximum automatic-reload spend for the billing period.

Read the quote shown by the Portal before saving. It is the current source for what the selected amount buys. Avoid copying plan names, rates, or allowance figures from documentation into application logic.

Saving the setting does not charge the payment method. When billing is enabled, reload attempts use an idempotent identity so a network retry refers to the same charge. A failed charge adds no allowance and may pause automatic reload. The environment's Portal and receipts are the source of truth for status, retry behavior, notifications, and credited allowances.

See Billing models for the SDK read-model boundary.