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

# Account, Verify and Lookup

> Account details and balance, usage and spend, subaccounts, OTP verification sessions, and carrier lookup.

Check your account balance and usage, manage subaccounts, verify phone numbers, or look up their carriers. After [logging in](https://plivo.com/docs/cli/install.md#log-in-with-a-browser), start with your account details:

```bash theme={null}
plivo account get
```

* Applications (the webhook URLs a number points at) are on [Connect a number](https://plivo.com/docs/cli/voice-agent/connect-number.md).
* Replace `<values>` with your own and omit `[flags]` unless adding options.
* Paged lists take `--limit`, `--offset` and `--all`. Global flags: see [Configuration](https://plivo.com/docs/cli/configure.md).

## Account

| Usage | What it does |
| - | - |
| `plivo account get` | Get account details (name, billing mode, credits, address) |
| `plivo account update [flags]` | Update account profile fields |
| `plivo account usage [flags]` | Show usage and spend for a date window. See [Usage and spend](#usage-and-spend). |

> [accordion] plivo account update
>
> | Flag | Description |
> | - | - |
> | `--address <value>` | billing address |
> | `--city <value>` | city |
> | `--name <value>` | account name |
> | `--timezone <value>` | IANA timezone (e.g. Asia/Kolkata) |

## Usage and spend

`plivo account usage` shows what the account used and spent over a date window. It needs CLI v1.3.0 or later and reads Plivo's [Usage Summary API](https://plivo.com/docs/account/api/usage-summary.md). Use it for any question about spend: adding up call or message records gives a different, incomplete number. To check the balance instead, use `plivo auth whoami` or `plivo account get`.

It prints a usage row per period, product, type, country and direction; other charges (number rentals, number lookups, fees, taxes); and the total spend with its currency. The `CAUSE` column appears when rows carry an error code or a hangup cause.

```bash theme={null}
plivo account usage --since 2026-10-01 --until 2026-11-01 --granularity month
```

```text theme={null}
PERIOD   PRODUCT  TYPE  COUNTRY  DIRECTION  UNITS  DURATION  AMOUNT   CAUSE
2026-10  message  sms   US       outbound   259              2.0461
2026-10  message  sms   US       outbound   4                0.0316   1000 Unknown error
2026-10  voice    pstn  US       inbound    2      359       0.0510
2026-10  voice    pstn  US       outbound   2      359       0.0840

PERIOD   OTHER CHARGE    UNITS  AMOUNT
2026-10  Number Lookup   8      0.0320
2026-10  Number Charges  2      1.0000

total_spend:  3.2447
currency:     USD
```

### The date window

* `--since` and `--until` are UTC dates, `YYYY-MM-DD`. `--from-date` and `--to-date` are the same flags.
* `--until` is exclusive: `--until 2026-11-01` ends with October 31. The call and message lists differ: there a bare `--until` date includes that whole day.
* Without `--since`, the window is the 7 days before `--until`. Without `--until`, the window ends at the start of today in UTC. With no dates you get the previous seven complete days.
* A window that holds no day, such as an `--until` that isn't after `--since`, is refused before any request.

`--granularity` sets the period of each row. Plivo limits the window for each:

| `--granularity` | Longest window |
| - | - |
| `hour` | 7 days |
| `day` (Plivo's default) | 92 days |
| `month` | 24 months |
| `year` | no limit |

The CLI doesn't check a longer window. The API refuses it with a 400, printed as a `VALIDATION_ERROR` (exit code `1`), for example `granularity=day supports a max window of 92 days (requested 122 days); use granularity=month for larger windows`.

### Filters

| Flag | Values |
| - | - |
| `--product` | `message`, `voice`, `zentrunk` (SIP trunking), `transcription` or `other`. Repeat it, or give a comma-separated list. |
| `--direction` | `inbound` or `outbound`, lower case |
| `--country` | A two-letter country code, such as `US` or `IN` |
| `--subaccount` | A subaccount's auth ID |
| `--hangup-cause` | Voice and SIP trunk rows with this hangup cause |
| `--error-code` | Message rows with this error code |

A value outside these is refused with `BAD_FLAG` before any request. Other charges are left out with `--subaccount`, or when `--product` leaves out `other`. `total_spend` then covers only the matching usage rows.

### Pages and output

`--limit` sets usage rows per page, from 1 to 1000 (default 100). There is no `--offset`. `--all` reads every page of usage rows; the totals and other charges come with the first page and already cover the whole window. Plivo allows 20 requests a minute on this API, so `--limit 1000 --all` needs the fewest requests.

| `-o` | What you get |
| - | - |
| `table` | The usage rows, the other charges, then `total_spend` and `currency` |
| `json`, `yaml` | The API response under `data`: `meta` (window, currency, `total_spend`), `usage[]` and `other_charges[]` |
| `jsonl`, `csv` | One record per usage row. The totals and other charges are only in `json`, `yaml` and the table. |

```bash theme={null}
plivo account usage                                                   # the last 7 days, by day
plivo account usage --since 2026-10-01 --product voice --direction outbound --all -o json
plivo account usage --since 2026-10-01 --until 2026-11-01 --granularity month --query 'data.meta.total_spend'
plivo account usage --since 2026-10-01 --granularity day --all --limit 1000 -o csv > usage.csv
```

## Subaccounts

A subaccount separates resources under your main Plivo account. Its `auth_token` and `new_auth_token` read `[REDACTED]` in every output format. `create` still shows the new token once. Add `--show-secrets` to see them in other output.

| Usage | What it does |
| - | - |
| `plivo account subaccounts create [flags]` | Create a subaccount |
| `plivo account subaccounts list [flags]` | List subaccounts |
| `plivo account subaccounts get <subauth_id>` | Get a subaccount by auth\_id |
| `plivo account subaccounts update <subauth_id> [flags]` | Update a subaccount |
| `plivo account subaccounts delete <subauth_id>` | Delete a subaccount (requires --yes) |

> [accordion] plivo account subaccounts create
>
> | Flag | Description |
> | - | - |
> | `--enabled` | enable on creation (default true) |
> | `--name <value>` | subaccount name (required) |

> [accordion] plivo account subaccounts update
>
> | Flag | Description |
> | - | - |
> | `--enabled <value>` | true\|false |
> | `--name <value>` | new name |

## Verify

Send a one-time password (OTP) and validate the code the recipient enters. Enable Verify and create a Verify application first; use its ID as `--app-uuid`. See the [Verify API](https://plivo.com/docs/programmable-api/verify/api-overview.md).

```bash theme={null}
plivo verify sessions create --app-uuid "<app_uuid>" \
  --recipient +14155550101 --channel sms --dry-run
```

Swap `--dry-run` for `--yes` to send the code. Then submit the received code with `plivo verify sessions validate "<session_uuid>" --otp "<code>"`.

| Usage | What it does |
| - | - |
| `plivo verify sessions create [flags]` | Create a Verify session (spends money: requires --yes) |
| `plivo verify sessions validate <session_uuid> [flags]` | Submit the OTP (`--otp <value>`, required) to validate a session |
| `plivo verify sessions get <session_uuid>` | Get a Verify session by uuid |
| `plivo verify sessions list [flags]` | List Verify sessions |

> [accordion] plivo verify sessions create
>
> | Flag | Description |
> | - | - |
> | `--app-uuid <value>` | Verify application uuid (required) |
> | `--channel <value>` | delivery channel: sms\|voice\|whatsapp (default "sms") |
> | `--explain` | narrate in plain English before executing |
> | `--locale <value>` | language and region code, such as `en-US` (BCP-47) |
> | `--method <value>` | HTTP method for callback URL |
> | `--recipient <value>` | E.164 destination number (required) |
> | `--url <value>` | callback URL for session status events |

> [accordion] plivo verify sessions list
>
> | Flag | Description |
> | - | - |
> | `--status <value>` | filter by status: in-progress\|verified\|expired |
>
> The API puts the rows at `data.sessions`. `--all`, `-o jsonl` and `-o csv` read them there.

## Lookup

Look up the carrier, number type and formatting for an E.164 number (country code plus number, such as `+14155550101`) through lookup.plivo.com.

```text theme={null}
plivo lookup <number> [flags]
```

| Flag | Description |
| - | - |
| `--type <value>` | lookup type (currently only 'carrier' is supported by Plivo) (default "carrier") |

> [!WARNING]
>
> Each lookup is billed, USD 0.004 per request, and the CLI notes the charge on stderr on each run. It takes no `--yes`, so it runs without confirmation. Preview with `plivo lookup +14155550101 --dry-run`, which prints the request without sending it.