Commands

Usage

Every read command takes a window: --duration today | week | month | quarter, or an explicit --since and --until.

--duration month is the trailing 30 days, not the calendar month. Use --since and --until for calendar boundaries.

paygent usage cost

What one customer cost and earned.

$paygent usage cost --customer acme
$paygent usage cost --customer acme --since 2026-07-01 --until 2026-07-31

paygent usage agent

What one agent cost and earned. Voice agents also report talk time and the per-minute or per-pulse average.

$paygent usage agent --agent support-bot

paygent usage breakdown

One customer’s cost split by agent.

$paygent usage breakdown --customer acme --fast

--fast skips the per-indicator provider and model sub-queries.

paygent usage customers

One agent’s cost split by customer.

$paygent usage customers --agent support-bot

paygent usage providers

Cost by AI service provider. Without --provider this lists every provider.

$paygent usage providers
$paygent usage providers --provider openai

paygent usage account

Cost and revenue across the whole organization.

$paygent usage account

paygent usage indicators

How often each indicator fired, and what share of activity it is.

$paygent usage indicators --agent support-bot

paygent usage export

Write a usage report to a file. --format csv flattens nested fields with dotted keys.

$paygent usage export --customer acme --format csv --out usage.csv
FlagDescription
--customer <c> or --agent <a>Exactly one is required.
--format <fmt>csv or json.
--out <path>File to write, or - for stdout. Required.

paygent usage send

Report one usage event. This is a debugging tool — real applications report from an SDK, in-process.

$paygent usage send --agent support-bot --customer acme \
>  --indicator chat --provider openai --model gpt-4o \
>  --input-tokens 1200 --output-tokens 340
FlagDescription
--agent, --customer, --indicatorRequired. Your own external IDs.
--provider, --modelRequired.
--input-tokens, --output-tokens, --cached-tokensToken counts.
--audio-duration, --characters, --video-durationVoice and video units.
--v1Use the strict path, which validates the agent up front.

The default path answers 202 Accepted, not 201. The event is queued and priced asynchronously, so success means accepted, not recorded. --v1 is the only path that reports AGENT_INACTIVE.

This command needs an API key, not a session token.