--- name: cargo-billing description: "Understand what Cargo is costing — remaining credits, usage broken down by workflow, connector, or agent, subscription state, and invoice history. Triggers: \"how many credits do I have left\", \"what did that cost\", \"why is my bill so high\", \"am I about to run out\", \"will this fit in our budget\", \"show me my invoices\", \"how much have I spent this month\", \"what plan am I on\", \"what do I get for free\", \"how many free credits\", \"can I afford this run\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics." version: "1.0.3" compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token homepage: https://github.com/getcargohq/cargo-skills metadata: author: getcargo openclaw: requires: bins: - cargo-ai install: - kind: node package: "@cargo-ai/cli@latest" bins: - cargo-ai homepage: https://github.com/getcargohq/cargo-skills --- # Cargo CLI — Billing Billing and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits. > See `references/response-shapes.md` for full JSON response structures. > See `references/troubleshooting.md` for common errors and how to fix them. > See `references/examples/usage-metrics.md` for usage metric and subscription examples. ## Bootstrap Already signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section. ```bash npm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli` cargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use # alternatives: --oauth (browser) · --token (CI) cargo-ai whoami # confirm the active workspace before any write ``` Every command prints JSON to stdout; failures exit non-zero with `{"errorMessage": "..."}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. **Admin-only:** every command in this skill requires a token with admin access on the workspace. Non-admin tokens return `{"errorMessage":"forbidden"}`. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface. ## Discover resources first Usage metrics can be filtered and grouped by resource UUID. Discover them before querying. ```bash cargo-ai orchestration play list # all plays (name, workflowUuid) cargo-ai orchestration tool list # all tools (name, workflowUuid) cargo-ai ai agent list # all agents (uuid, name) cargo-ai connection connector list # all connectors (uuid, name, integrationSlug) cargo-ai storage model list # all models (uuid, name, slug) ``` ## Quick reference ```bash cargo-ai billing usage get-metrics --from --to cargo-ai billing usage get-metrics --from --to --group-by workflow_uuid cargo-ai billing subscription get cargo-ai billing subscription get-invoices cargo-ai billing subscription create-portal-session ``` ## Estimating cost before running a batch Before triggering a large batch, estimate credit consumption to avoid unexpected charges. **Step 1 — Check current credit balance:** ```bash cargo-ai billing subscription get # → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits ``` **Step 2 — Estimate cost from a sample run:** Run the workflow on a single record first and measure credits consumed: ```bash # Run on one record cargo-ai orchestration run create --workflow-uuid --data '{...}' # → poll to completion # Check credits used for that run cargo-ai billing usage get-metrics \ --from --to \ --workflow-uuid # → .totalUsage = credits consumed today for this workflow ``` **Step 3 — Project batch cost:** ``` estimated_cost = credits_per_record × number_of_records ``` Compare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding. **Step 4 — Monitor during the batch:** ```bash # Check running costs mid-batch cargo-ai billing usage get-metrics \ --from --to \ --workflow-uuid ``` **Cost levers:** | Action | Effect | |---|---| | Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes | | Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls | | Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes | | Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record | > To find out **which** node or provider dominates a play's spend before picking a lever, follow the attribution runbook in [`../cargo-diagnostics/references/play-optimize-credits.md`](../cargo-diagnostics/references/play-optimize-credits.md). ## Usage metrics Pull credit and usage data for any time range, optionally filtered and grouped. ```bash # Basic usage for a period cargo-ai billing usage get-metrics --from --to # Group by dimension cargo-ai billing usage get-metrics --from --to --group-by workflow_uuid cargo-ai billing usage get-metrics --from --to --group-by connector_uuid cargo-ai billing usage get-metrics --from --to --group-by integration_slug cargo-ai billing usage get-metrics --from --to --group-by model_uuid cargo-ai billing usage get-metrics --from --to --group-by agent_uuid # Filter by specific resource cargo-ai billing usage get-metrics --from --to --workflow-uuid cargo-ai billing usage get-metrics --from --to --agent-uuid cargo-ai billing usage get-metrics --from --to --connector-uuid cargo-ai billing usage get-metrics --from --to --integration-slug # Specify unit cargo-ai billing usage get-metrics --from --to --unit credits ``` `--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`. Available filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`. ## Subscription and credits ```bash cargo-ai billing subscription get # current plan, credits used/available, period dates cargo-ai billing subscription get-invoices # invoice history (amounts in cents) cargo-ai billing subscription get-credit-card # card on file cargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing ``` Remaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`. **Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value. ### The free tier A new account starts with **100 free credits and no card on file**. When `subscription get` shows a fresh or near-fresh balance, answer cost questions against that budget rather than as an abstract number — "you've used 12 of your 100 free credits" is the useful answer to "how am I doing?", and it is also the honest one when the user is deciding whether to keep going. What 100 credits buys, as ballpark anchors (per-action costs in [`../cargo-gtm/references/credits-cost-table.md`](../cargo-gtm/references/credits-cost-table.md)): | Work | Cost | 100 credits ≈ | |---|---|---| | Source leads — `salesNavigator.searchLeads` | 0.02/record | ~5,000 leads | | Enrich from a LinkedIn URL + verified email — `aiArk.enrichPerson` | 0.1 | ~1,000 people | | Verify an email — `waterfall.verifyEmail` | 0.1 | ~1,000 checks | | Full contact enrichment — `waterfall.enrichContact` | 2 | ~50 contacts | | Find a phone — `FullEnrich.findPhone` | 6 | ~16 numbers | The [quickstart demo](../cargo-quickstart/SKILL.md) spends about **0.5**. Phone lookups are the fastest way to burn a free tier, so phone is the **guarded lever**: the escalation tier runs 3–7 credits/record, ~10× email, and never belongs in a default chain — it enters a plan only on explicit user request, on qualified leads only. Full spend rules in [`../cargo-gtm/references/cost-discipline.md`](../cargo-gtm/references/cost-discipline.md). ## Help Every command supports `--help`: ```bash cargo-ai billing usage get-metrics --help cargo-ai billing subscription get --help cargo-ai billing subscription get-invoices --help ```