v1.0.3 to v1.0.3

27 added, 4 removed. Audit A to A.

---

name: cargo-billing

- description: Pull usage metrics, check subscription status, view invoices, and manage credits using the Cargo CLI. Use when the user wants billing analytics, usage reports, credit usage, cost analysis, subscription details, or invoice history for their Cargo workspace.

+ 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.

- ## Prerequisites

+ ## Bootstrap

- See [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) for install, login (`--oauth` / `--token`), JSON output conventions, and error shapes. Verify the session with `cargo-ai whoami` before running any of the commands below.

+ Already signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.

- **Admin-only:** every command in this skill requires a token with admin access on the workspace. Non-admin tokens return `{"errorMessage":"forbidden"}`.

+ ```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 <api-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 <YYYY-MM-DD> --to <YYYY-MM-DD>

cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --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 <uuid> --data '{...}'

# → poll to completion

# Check credits used for that run

cargo-ai billing usage get-metrics \

--from <today> --to <today> \

--workflow-uuid <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 <start-date> --to <today> \

--workflow-uuid <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 <start-date> --to <end-date>

# Group by dimension

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by workflow_uuid

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by connector_uuid

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by integration_slug

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by model_uuid

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by agent_uuid

# Filter by specific resource

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --workflow-uuid <uuid>

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --agent-uuid <uuid>

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --connector-uuid <uuid>

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --integration-slug <slug>

# Specify unit

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --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

```