Skip to main content

Tokens overview

Tokens pay for supported LeadsParrot actions such as enrichment and AI generation. They belong to the account, not to an individual user. The Tokens page reconciles the full account balance into shared available, in workspace buckets, and held for actions.

See token costs by action for the live prices and charging conditions used by Lead Intelligence, AI features, and campaign sending.

The balance explorer uses an exclusive allocation: total balance = shared available + workspace available + shared account held + workspace bucket held. The two held values appear together under Held for actions and remain available for separate inspection.

Essential terms​

  • Total balance: all unspent account-owned tokens.
  • Shared tokens: tokens available to account-scope actions and to workspaces configured to use the shared balance.
  • Workspace token bucket: existing account tokens earmarked for one workspace. Moving tokens into a bucket does not buy, grant, or create tokens.
  • Monthly workspace cap: an independent spending ceiling that resets at the start of each UTC calendar month.
  • Shared account held: tokens temporarily reserved for actions from the shared account balance.
  • Workspace bucket held: tokens temporarily reserved for actions from workspace buckets.
  • Held for actions: the combined shared-account and workspace-bucket holds shown in the balance explorer.
  • Effective availability: the lower of the selected source availability and the remaining monthly cap after active holds.

Account-scope actions that use tokens always use shared tokens. A workspace administrator chooses either shared tokens or that workspace's bucket. The workspace uses that source exclusively; an empty bucket never falls back to shared tokens.

Use Numbers, Flow, Sunburst, or Layered to view the same balance hierarchy. Numbers is the default, leftmost view and uses direct number blocks and workspace rows; the other modes use interactive visual geometry. Select a branch for an explanation, or select a workspace to inspect its available and held bucket tokens. Zero-value categories stay in the textual summary and selection controls without being given a misleading visual size.

Campaign email send charges​

Before each campaign send, LeadsParrot places the current send-cost hold against the workspace's selected token source and monthly cap. See token costs by action for the live cost. The outcome determines what happens next:

  • Accepted by the sending provider: LeadsParrot captures the hold as the final charge.
  • Confirmed failure: LeadsParrot releases the hold, and the email is not charged.
  • Insufficient token availability or monthly cap: LeadsParrot does not send or charge the email. The affected lead waits, and the campaign retries later.
  • Retry of the same campaign email: LeadsParrot settles the existing send reservation so the same email is not charged twice.

The charge applies to every successfully sent campaign email step. The live cost page includes examples calculated from current backend pricing.

A quick example​

An account has 1,000 tokens. An administrator puts 200 into the Acme workspace bucket, leaving 800 shared. If Acme also has a 100-token monthly cap, it can spend at most 100 this UTC month. The bucket's remaining 100 carries forward and becomes usable after the next monthly reset.

Continue with account balances and sources, workspace buckets and caps, or spending and holds.