> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Usage

> Read what your agents cost and earned, and report events.

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

> **Warning**
>
> `--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.

```bash
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.

```bash
paygent usage agent --agent support-bot
```

## `paygent usage breakdown`

One customer's cost split by agent.

```bash
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.

```bash
paygent usage customers --agent support-bot
```

## `paygent usage providers`

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

```bash
paygent usage providers
paygent usage providers --provider openai
```

## `paygent usage account`

Cost and revenue across the whole organization.

```bash
paygent usage account
```

## `paygent usage indicators`

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

```bash
paygent usage indicators --agent support-bot
```

## `paygent usage export`

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

```bash
paygent usage export --customer acme --format csv --out usage.csv
```

| Flag                              | Description                                 |
| --------------------------------- | ------------------------------------------- |
| `--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.

```bash
paygent usage send --agent support-bot --customer acme \
  --indicator chat --provider openai --model gpt-4o \
  --input-tokens 1200 --output-tokens 340
```

| Flag                                                   | Description                                              |
| ------------------------------------------------------ | -------------------------------------------------------- |
| `--agent`, `--customer`, `--indicator`                 | Required. Your own external IDs.                         |
| `--provider`, `--model`                                | Required.                                                |
| `--input-tokens`, `--output-tokens`, `--cached-tokens` | Token counts.                                            |
| `--audio-duration`, `--characters`, `--video-duration` | Voice and video units.                                   |
| `--v1`                                                 | Use the strict path, which validates the agent up front. |

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