Spend, Budgets, and API Tokens

Use verdictan spend to examine recorded spending. Use verdictan token to limit an application credential by provider, model, spend, request count, or expiry.

All commands use API authentication. Set VERDICTAN_API_TOKEN, or sign in with verdictan auth login before you run them. Each command accepts --json. The verdictan spend commands accept the standard overrides --config <path>, --api-url <url>, --profile <name>, and --region <region>. The verdictan token commands accept --config <path>, --api-url <url>, and --profile <name> only. The tables below list only the command-specific flags.

Examine recorded cost

verdictan spend summary --since 7d --group-by region --json

Read these values as estimated costs from recorded usage. They are not your provider invoice. If usage or pricing is missing, the total does not include all costs.

Before you create a limit, select the control that applies to your request path:

Control	Use it for
Governed token limits	Limit requests made with a specified application token.
Provider budget	Limit provider headroom when targets have pricing metadata.
Scope budget	Store an organization, team, user, or key budget. Connected gateways do not load these records for routing.

For a procedure to configure and verify a token limit, see Usage costs and budgets.

verdictan spend summary

verdictan spend summary returns the spend report for the organization.

Usage

verdictan spend summary [--since <duration|rfc3339>] [--group-by <dimension>] [--json]

Options

Flag	Description
--since <duration|rfc3339>	Start of the report window. Accepts an RFC3339 UTC timestamp or a relative duration such as 30d.
--group-by <dimension>	Group the totals by one dimension, such as region.

Examples

verdictan spend summary
verdictan spend summary --since 30d --group-by region --json

verdictan spend budget

verdictan spend budget manages scope budgets at /v1/budgets. A scope budget applies to an organization, a team, a user, or a key.

Usage

verdictan spend budget list [--json]
verdictan spend budget get --budget-id <id> [--json]
verdictan spend budget create --name <name> --max-budget <amount> --target-type <type> [OPTIONS]
verdictan spend budget update --budget-id <id> [OPTIONS]
verdictan spend budget delete --budget-id <id> --yes

Options

Flag	Applies to	Description
--budget-id <id>	get, update, delete	Mandatory budget ID.
--name <name>	create, update	Budget name. Mandatory for create.
--max-budget <amount>	create, update	Maximum amount. Mandatory for create.
--target-type <key|user|team|organization>	create	Mandatory scope of the budget.
--target-id <id>	create	ID of the key, user, or team. Mandatory for those target types.
--currency <code>	create, update	Currency code. The default for create is usd.
--reset-schedule <schedule>	create, update	Reset schedule: never, daily, weekly, or monthly. The API rejects any other value with 422. A budget without a schedule does not reset.
--alert-threshold-pct <n>	create, update	Alert threshold as a percentage. The default for create is 80.
--yes	delete	Mandatory confirmation. Without it, the command stops with an error and makes no changes.

Examples

# Store an organization-level monthly budget
verdictan spend budget create \
  --name "Monthly planning budget" \
  --max-budget 100 \
  --target-type organization \
  --reset-schedule monthly

# Team budget with an earlier alert
verdictan spend budget create \
  --name "Support Team" \
  --max-budget 25 \
  --target-type team \
  --target-id team_abc123 \
  --alert-threshold-pct 70

# Raise a limit, then confirm the stored value
verdictan spend budget update --budget-id budget_abc123 --max-budget 150
verdictan spend budget get --budget-id budget_abc123 --json

Reset periods are in UTC. A daily period starts at 00:00 UTC, a weekly period on Monday, and a monthly period on the first day of the month. When a period ends, the budget shows zero spend.

A standalone gateway with an event sink can use the remaining scope budget when it selects a priced target. A connected gateway does not load scope budgets for routing. For the connected request path, use provider budgets, governed token limits, and usage authorization. Usage Costs and Budgets gives details about the difference.

verdictan spend provider-budget

verdictan spend provider-budget manages spend limits for one provider. The gateway uses provider budgets in its provider-headroom check.

Usage

verdictan spend provider-budget list [--json]
verdictan spend provider-budget get --budget-id <id> [--json]
verdictan spend provider-budget create --provider <name> --limit-usd <amount> [--reset-schedule <schedule>] [--reset-at <time>] [--json]
verdictan spend provider-budget delete --budget-id <id> --yes

Options

Flag	Applies to	Description
--budget-id <id>	get, delete	Mandatory provider budget ID.
--provider <name>	create	Mandatory provider name, such as openai or anthropic.
--limit-usd <amount>	create	Mandatory limit in USD.
--reset-schedule <schedule>	create	Reset schedule: daily, weekly, monthly, or lifetime (no reset). The default is monthly. --period is an alias.
--reset-at <time>	create	Next reset time as an RFC 3339 timestamp. It also sets the start of later periods.
--yes	delete	Mandatory confirmation. Without it, the command stops with an error and makes no changes.

Examples

verdictan spend provider-budget create --provider openai --limit-usd 25 --reset-schedule monthly
verdictan spend provider-budget list --json

To remove a provider budget that is not in use, copy its ID from list. Then run verdictan spend provider-budget delete --budget-id "$BUDGET_ID" --yes. Removal changes provider headroom.

Before you use a provider budget, make sure that the target has pricing metadata. Send one allowed request through the gateway. Then verify that the gateway blocks a request when the budget is exhausted.

verdictan token

verdictan token governs the API tokens that applications, IDEs, gateways, and integrations use. The token ID is a positional argument for each subcommand that acts on one token.

Usage

verdictan token list [--purpose <purpose>] [--alerts-only] [--json]
verdictan token get <id> [--json]
verdictan token create --name <name> [OPTIONS]
verdictan token update <id> [OPTIONS]
verdictan token clone <id> --reason <text> [OPTIONS]
verdictan token rotate <id> [--json]
verdictan token validate [--force-tty] [--json]
verdictan token delete <id> --yes [--json]
verdictan token emergency-revoke <id> --reason <text> --yes [--revoke-active-sessions] [--json]
verdictan token exchange-code [OPTIONS]

verdictan auth documents verdictan token exchange-code, which changes a PKCE authorization code into one API token.

Options

Flag	Applies to	Description
<id>	get, update, clone, rotate, delete, emergency-revoke	Mandatory positional token ID.
--purpose <general|gateway-runtime|integration>	list, create	Token purpose. For list, return only one purpose. For create, the default is general.
--alerts-only	list	Return only tokens with a budget, request, expiry, or terminal alert.
--name <name>	create, update, clone	Display name. Mandatory for create.
--key-class <durable|virtual|disposable>	create	Governed key class. The default is durable.
--provider <name>	create, update, clone	Provider binding. update and clone can only narrow it.
--model-filter <model>	create, update, clone	Model filter. Supply the flag for each value, or pass values with commas between them.
--gateway-id <id>	create, update, clone	Gateway binding.
--team-id <id>	create, update, clone	Team binding.
--budget-id <id>	update, clone	Budget binding.
--rate-limit-rpm <n>	create, update, clone	Requests for each minute. update and clone can only lower it.
--rate-limit-tpm <n>	create, update, clone	Tokens for each minute. update and clone can only lower it.
--max-budget <amount>	create, update, clone	Maximum spend for the token. update and clone can only lower it.
--max-requests <n>	create, update, clone	Maximum request count. update and clone can only lower it.
--currency <code>	create, update, clone	Budget currency, such as USD.
--metadata-json <json>	update, clone	Replace the public token metadata with one JSON object.
--policy-id <id>	update, clone	Replace the attached policy IDs. Supply the flag for each value, or pass values with commas between them.
--expires-in <duration>	create	Expiry duration, such as 30d or 24h.
--expires-in-seconds <n>	clone	Expiry duration in seconds.
--expires-at <timestamp>	clone	Expiry timestamp in the format that the API accepts.
--reason <text>	clone, emergency-revoke	Mandatory lifecycle reason.
--revoke-active-sessions	emergency-revoke	Also revoke the active sessions of the token subject when applicable.
--force-tty	validate	Accept the token value from an interactive terminal as an alternative to a pipe.
--yes	delete, emergency-revoke	Mandatory confirmation. Without it, the command stops with an error and makes no changes.

Create a bounded application token

This example creates a short-lived token with a small spending limit and at most three requests:

verdictan token create \
  --name docs-request-test \
  --purpose general \
  --key-class disposable \
  --max-budget 1 \
  --max-requests 3 \
  --expires-in 1h

Save the returned token value immediately. It shows one time. Keep the token ID for subsequent management. Before use, apply the necessary gateway, provider, and model bindings.

The limits apply to requests made with this token. They do not limit traffic that uses other credentials.

Update or copy a configured token

Set TOKEN_ID to an ID from verdictan token list. An update can narrow its limits:

verdictan token update "$TOKEN_ID" --max-requests 2
verdictan token get "$TOKEN_ID" --json

To make a narrower copy for a different task:

verdictan token clone "$TOKEN_ID" \
  --reason "Isolated documentation test" \
  --model-filter "replace-with-an-allowed-model-id"

Rotate a token

Rotation replaces the raw credential. Prepare to update its consumers before you run this command:

verdictan token rotate "$TOKEN_ID"

Save the new value. Update the application. Send a request with the replacement to verify it.

Validate or revoke a token

Validation reads the candidate value from standard input:

printf '%s' "$CANDIDATE_TOKEN" | verdictan token validate

To revoke a token that is no longer necessary:

verdictan token delete "$TOKEN_ID" --yes

If you think that the credential was exposed, record the reason with an emergency revocation:

verdictan token emergency-revoke "$TOKEN_ID" \
  --reason "Suspected credential exposure" --yes

Task	Subcommand
Create a new bounded token	create
Narrow metadata, bindings, limits, or policies of one token	update
Create a narrower copy of one token record	clone
Replace the raw value and keep the record	rotate
Verify a raw value against the API	validate
Revoke with proof metadata	emergency-revoke

Limits and failure behavior

• All commands stop with an authentication error when no API token or session is available.
• verdictan token commands do not accept --api-token or --region. Use VERDICTAN_API_TOKEN or a stored profile.
• spend budget delete, spend provider-budget delete, token delete, and token emergency-revoke do not prompt. They stop with an error unless you pass --yes.
• token create, token clone, and token rotate show the raw token value one time. Store the value immediately and keep JSON output out of logs.
• token validate reads the raw token from standard input. When standard input is a terminal, the command stops unless you pass --force-tty. Do not put a token value in shell history or process arguments.
• token rotate returns a replacement value. Update each consumer immediately, and do not give the previous value to consumers.
• token update and token clone narrow a token. They do not widen a binding or increase a limit.
• A scope budget is a stored record. It does not enforce spend on a connected gateway.
• A provider budget uses pricing metadata on the target. Verify one allowed request. Then verify that the gateway blocks a request when the budget is exhausted.

Next steps

• Manage API Tokens: create and give tokens for applications and IDEs.
• Usage Costs and Budgets: learn which budget control acts on which request path.
• verdictan auth: sign in, and run verdictan token exchange-code for an OAuth flow.