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, start with your account details:

plivo account get

• Applications (the webhook URLs a number points at) are on Connect a number.
• Replace <values> with your own and omit [flags] unless adding options.
• Paged lists take --limit, --offset and --all. Global flags: see Configuration.

​

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.

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

plivo account usage --since 2026-10-01 --until 2026-11-01 --granularity month

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.

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)

plivo account subaccounts create

Flag	Description
--enabled	enable on creation (default true)
--name <value>	subaccount name (required)

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.

plivo verify sessions create --app-uuid "<app_uuid>" \
  --recipient [phone] --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

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

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 [phone]) through lookup.plivo.com.

plivo lookup <number> [flags]

Flag	Description
--type <value>	lookup type (currently only ‘carrier’ is supported by Plivo) (default “carrier”)

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 [phone] --dry-run, which prints the request without sending it.