Credits, quotas, and plans

Follow the shared cost policy in workflows-discover-actions/cost-and-budget.md. Check headroom internally before paid work; do not announce balances or suggest purchases just because a tool returned billing data. Stop and explain a verified shortfall rather than knowingly starting a partial run. An unknown cost does not establish a shortfall or require a cost-only approval.

Triage

After checking what remains (below), route by what is short:

• balance short — CLI top-up or billing UI (addCredits). Prefer auto top-up.
• actionExecutionBalance short (when the field is present) — plan selector only. There is no top-up for action executions. Do not offer once, auto, or addCredits.
• Search quota_exceeded or period cap exhausted — plan selector and/or wait for the named reset in the error message. Defer shrink/retry rules to the search skill; do not invent a top-up path for result caps.

Plan selector URL (upgrade or change plan):

clay whoami | jq -r '.workspace.id'

https://app.clay.com/workspaces/<workspaceId>/billing/plan-selector

Check what remains

clay credits balance | jq '{ balance, actionExecutionBalance }'

balance is the data-credit pool. actionExecutionBalance is optional — present only on action-execution pricing plans; omit or ignore it when the field is null or absent (legacy billing). Plenty of one does not cover the other.

For routine runs, clay routines get <id> includes per-item cost estimates. When the estimate applies to the configured execution and its counts are known, multiply each cost by the number of items and compare against the matching balance. See the routines skill for estimate limitations and the stop-before-partial-run rule.

Read clay credits balance --help for field semantics.

CLI top-up

Applies to data-credit balance only — not actionExecutionBalance.

Prefer auto top-up. Lead with enabling (or confirming) auto so the workspace stays funded without another interrupt. Only offer a one-time purchase if the user pushes back against auto, or if auto is unavailable.

Read clay credits top-up <subcommand> --help for the exact JSON output shape, flags, and examples; that help is the contract.

clay credits top-up auto get
clay credits top-up auto enable --threshold <n> --credits <n> [--daily-spend-limit-cents <n|none>]
clay credits top-up auto disable
clay credits top-up once --credits <n> [--open]   # only if user declines auto, or auto unavailable

Auto enable limits:

• --credits: at least 250 data credits; the plan-specific maximum is the number of credits currently equivalent to $1000
• --daily-spend-limit-cents: optional rolling 24-hour cap, 3000–500000, or none to clear; must cover the current price of one top-up
• --threshold: credit balance that triggers a top-up; must be at least 15% of the workspace subscription-cycle credit allowance (the server error includes the exact minimum when too low)

If the current balance is already at or below --threshold when auto is enabled, a top-up runs immediately — it does not wait for the next charge. Tell the user that enabling auto can purchase credits right away when they are already under the threshold.

Auto get/disable return the same policy shape as enable.

Once (fallback): --credits must be at least 250. Returns a checkout url; --open launches it in the browser. Credits land only after checkout completes — do not treat command exit as a topped-up balance.

Errors worth knowing (from credits balance / credits top-up):

• auth_forbidden (exit 3) — billing-management access required
• not_found (exit 6) — auto top-up unavailable for this workspace, or disable when not currently enabled; fall back to once or the billing UI

Do not run top-up without explicit user confirmation. credits top-up commands are gated from auto-approval in the plugin — present options and wait for the user before auto enable, once, or checkout --open.

Billing UI

Prefer CLI auto first. Use the billing UI when the user wants the browser, or as the one-time fallback after they decline auto / auto is unavailable:

clay whoami | jq -r '.workspace.id'

https://app.clay.com/workspaces/<workspaceId>/home?addCredits=true

The addCredits=true query opens the buy-credits modal directly.

Search and result-cap quotas

There is no CLI to top up search result caps or period quotas. Auto top-up only replenishes credit shortfalls — it does not raise per-search or per-period result limits.

quota_exceeded (exit 1, HTTP 402) is a plan result cap or credit/usage limit — not a transient failure (do not retry with backoff). Prefer the plan selector over top-up unless the message is clearly a data-credit shortfall that top-up can fix. When the error is about results already requested vs a cap, or a named period reset, stop paging; for shrink/retry rules follow the searches skill's Quotas section — do not invent a top-up path for result caps.

Plan selector:

clay whoami | jq -r '.workspace.id'

https://app.clay.com/workspaces/<workspaceId>/billing/plan-selector