# polymorfa usage

> Commands under polymorfa usage.

## Commands

- [polymorfa usage gates](https://docs.polymorfa.com/cli/usage/gates): List usage gates and their limits.
- [polymorfa usage records](https://docs.polymorfa.com/cli/usage/records): List usage records.
- [polymorfa usage summary](https://docs.polymorfa.com/cli/usage/summary): Show metered usage for a month.

## polymorfa usage gates

List usage gates and their limits.

List your usage gates with their mode, limit, usage this month and how often an action went over the limit in the last 30 days. In record mode a gate never refuses an action; in enforce mode an action over the limit fails with gate_limit_reached. Pass --session to include limits that apply per number. Gate state covers the whole team, so this needs a team API key; project API keys are refused. A limit that cannot be checked fails the action with 503 in either mode.

### Usage

```bash
polymorfa usage gates [flags]
```

### Flags

- `--session <value>` (value). Include limits that apply to one number (session name).

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa usage gates
```

```bash
polymorfa usage gates --session support --json
```

## polymorfa usage records

List usage records.

List usage records, newest first. Filter by call, number, meter or calendar month. A call has one call.duration record, and an outgoing Cloud API call also a call.cloud_pulses record. Pass the printed cursor to read the next page.

### Usage

```bash
polymorfa usage records [flags]
```

### Flags

- `--call <value>` (value). One call, by call ID.
- `--cursor <value>` (value). Continue from a previous page.
- `--limit <value>` (value). Records per page, 1 to 100.
- `--meter <value>` (value). One meter, for example call.duration.
- `--period <value>` (value). Calendar month in UTC as YYYY-MM.
- `--session <value>` (value). Limit to one number (session name).

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa usage records --call 3EB0C431C26A1916E07A
```

```bash
polymorfa usage records --session support --meter call.duration --limit 50 --json
```

## polymorfa usage summary

Show metered usage for a month.

Show metered usage for one calendar month (UTC), by meter and by number. Usage is measured, not charged: no credits are deducted for it. Requires sessions:read. A project token reads only its own project.

### Usage

```bash
polymorfa usage summary [flags]
```

### Flags

- `--period <value>` (value). Calendar month in UTC as YYYY-MM. Defaults to this month.
- `--session <value>` (value). Limit to one number (session name).

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa usage summary
```

```bash
polymorfa usage summary --period 2026-09 --session support --json
```
