Billing

Swirls bills your organization on a credit model. Two meters cover everything that runs: execution credits for the work your workflows and agents do, and tool spend for the paid external capabilities your agents buy through their wallet. Plans set the included amounts; one-time top-ups extend them. Usage is reported per project so you can see which project spent what.

For current plans, prices, and per-node credit numbers, see swirls.ai/pricing. This page covers the mechanism.

The two meters

The meters are independent. An agent turn that pays for an external tool consumes both: the flat turn cost in credits, and the tool's price from the tool-spend balance.

Execution credits

Workflow runs

Each successful node execution spends credits. The cost depends on the node type:

• AI, agent, and vendor-backed nodes (scrape, search, parallel, disk) cost the most.
• Email and stream nodes sit in the middle.
• Plumbing nodes (code, http, postgres, database, integration, nested workflow) cost the least.
• Pure control flow (map, while, switch, wait) is free. The work it orchestrates is what gets billed.

Failed nodes are not billed. The current per-node numbers are on swirls.ai/pricing.

Jev decisions

A successful decision node costs 25 execution credits with either a customer-owned or managed TypeSafe key. Customer-owned keys incur TypeSafe's charges on your account. Managed keys require the existing Enterprise platform_keys entitlement and an explicit type: managed secret block. Managed decisions use the same execution-credit balance, exhaustion holds, and usage reporting as other workflow nodes; there is no additional token surcharge. Managed calls also have protective request limits described in the decision guide. Recorded native token usage is for inspection, and usage records distinguish platform keys from customer keys.

Agent turns

Talking to an agent directly bills a flat credit cost per turn, where a turn is one message you send. Swirls charges once per turn: sub-agent delegation and tool calls inside the turn do not multiply it. Turns that do not complete are not billed.

Enforcement

• Workflow runs check your credit balance before starting. When credits are exhausted, the run is parked on a billing hold instead of failing. The Billing page shows a banner with the held count; topping up or upgrading releases held work.
• Agent turns are rejected up front when credits are exhausted. The API returns HTTP 402 with code insufficient_credits, and the agent stops accepting new turns until your balance recovers.

Disabled projects

A project stops generating new execution-credit and tool-spend usage when disabling begins. Live work is cancelled while the transition completes, and a fully disabled project stays non-operational until it is enabled. Only active projects count toward organization project allowances.

Disabling is not a refund: completed work and external-provider charges already incurred remain in historical usage. Passive project data is retained, including deployments, databases, files, secrets, traces, and execution history. Enabling a project performs the normal active-project allowance check before execution admission reopens.

Agent tool spend and the wallet: budget

Agents pay for external capabilities through a per-agent wallet declared in the .swirls file:

agent poem_writer {
  ...
  wallet: {
    budget: 10       // USD per cadence window
    cadence: daily   // daily | weekly | monthly
    maxPerCall: 2    // optional USD ceiling per tool call
  }
}

budget caps what the agent may spend per cadence window. maxPerCall caps any single tool call; when omitted, a platform default applies. Declaring wallet: is what enables the paid external tools for that agent. See the wallet block for the agent-side details.

Enforcement is two-layer, and both layers return HTTP 402 when exceeded:

1. The agent's cadence budget. Spend is reserved before a paid call and settled after it. Exceeding the window's budget fails the call with agent_wallet_exceeded, and the agent's wallet stays closed until the window resets.
2. The organization's tool-spend balance. Every agent draws from the org-wide prepaid balance. When it is exhausted, paid calls fail with insufficient_tool_budget until you top up.

Plans and top-ups

• Free is inspection-only: author, deploy, and inspect, with no execution credits.
• Paid self-serve plans include a monthly credit allowance plus usage-based overage per credit. Larger plans include more credits at a lower overage rate. The entry plan carries a free trial.
• Enterprise removes self-serve limits, adds declarative managed vendor keys (type: managed), and is billed by your account team rather than self-serve checkout.

One-time top-ups are available on any paid plan: credit packs add execution credits, and tool budget packs add tool spend. Top-ups are added to your balance immediately.

Plan changes, top-up purchases, invoices, and payment details are all managed on the Billing page in the dashboard.

Where to see usage

The Billing page

Billing in the dashboard, at the organization level, shows:

• Your current plan, credits used this cycle, credit balance including top-ups, and tool budget balance.
• A billing-hold banner when runs are parked, with the held count.
• Credit usage by project, and tool spend by project and by agent, over a selectable range.
• Plan cards, top-up purchases, your invoices, and subscription management.

Each agent's detail panel also shows its wallet status: the window's budget, what is spent, what is reserved, and what remains.

The SDK

The billing client reads the same numbers programmatically:

Plan changes and payment are not SDK operations. They run through the Billing page.

Next steps

• swirls.ai/pricing: current plans, prices, and per-node credit numbers.
• Agents: the wallet: block and the paid tool catalog.
• SDK billing client: usage queries from your own code.