{"id":"fe630687-8760-4a22-9d9b-00aba7223e26","entityType":"agent","slug":"clawhub-cargo-ai-cargo-billing","name":"cargo-billing","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cargo-ai-cargo-billing","canonicalPath":"/agent/clawhub-cargo-ai-cargo-billing","generatedAt":"2026-10-10T11:51:48.889Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":null},"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\", \"add a card\", \"update my payment method\", \"why was my card declined\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s178dcd9wkfn0a2fqrygmt3jzn87j9e1:cargo-billing","sourceUrl":"https://clawhub.ai/cargo-ai/cargo-billing","homepage":"https://clawhub.ai/cargo-ai/skills/cargo-billing","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cargo-ai/cargo-billing","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cargo-ai/skills/cargo-billing","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"cargo-billing technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":null},"stars":null,"forks":null,"downloads":1538,"packageName":null,"latestVersion":"2.0.1","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T09:05:09.415Z","lastCrawledAt":"2026-10-10T09:05:09.415Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T09:05:09.415Z","lastVerifiedAt":null,"highlights":[{"version":"2.0.1","createdAt":"2026-10-02T18:32:01.349Z","changelog":"cargo-billing 2.0.1 - Updated version to 2.0.1 in SKILL.md and skill-metadata.json. - Removed outdated skill-card.md file. - No functional or CLI changes; documentation and metadata update only.","fileCount":7,"zipByteSize":13545},{"version":"2.0.0","createdAt":"2026-09-01T23:29:08.468Z","changelog":"cargo-billing 2.0.0 — Major update with revised usage metrics and cost estimation logic. - Updated usage metrics API: `get-metrics` now returns a `metrics` array; removed `totalUsage`. - Added detailed documentation on the new execution-based cost model, including the 0.01-credit-per-execution charge. - Expanded `--unit` values to `billing.credits`, `orchestration.executions`, and `storage.records` only. - Improved cost estimation steps and clarified impact levers for controlling spend. - Cleaned up example commands and removed deprecated documentation files.","fileCount":7,"zipByteSize":13741},{"version":"1.1.0","createdAt":"2026-08-13T03:18:22.964Z","changelog":"cargo-billing 1.1.0 - Expanded description to clarify skill triggers and use cases, with guidance on when to use alternative skills. - Added `update-payment-method` command for managing payment cards via CLI. - Improved onboarding and bootstrap instructions for new users. - Updated help and usage examples, including clear CLI flags and common user questions. - Removed deprecated `skill-card.md` file.","fileCount":7,"zipByteSize":10950},{"version":"1.0.3","createdAt":"2026-08-11T21:44:17.427Z","changelog":"- Updated to version 1.0.3. - Added skill-metadata.json and removed skill-card.md. - SKILL.md: Clarified compatibility requirements—sign-in now highlights `cargo-ai login --email` as an option and no longer requires browser sign-in. - Minor text and metadata adjustments for improved clarity.","fileCount":7,"zipByteSize":7631},{"version":"1.0.2","createdAt":"2026-07-10T00:55:46.903Z","changelog":"- Added a reference to the play cost attribution runbook to help users identify which node/provider dominates a play's credits spend. - Removed the redundant file: skill-card.md. - Updated version to 1.0.2.","fileCount":6,"zipByteSize":7022},{"version":"1.0.1","createdAt":"2026-05-28T22:13:26.635Z","changelog":"- Updated version to 1.0.1. - SKILL.md now references a shared prerequisites guide for install, login, and error conventions. - Clarified that all commands require an admin-level token; non-admin tokens result in a \"forbidden\" error. - Updated CLI installation instructions to use @cargo-ai/cli@latest. - No functional changes to commands or usage.","fileCount":6,"zipByteSize":7027},{"version":"1.0.0","createdAt":"2026-05-28T19:28:39.970Z","changelog":"Initial release of the cargo-billing skill. - Lets you pull usage metrics, analyze cost, and view credit consumption for your Cargo workspace using the Cargo CLI. - Check subscription status, invoice history, and manage billing or credits with simple CLI commands. - Includes quick cost estimation steps for batch runs to help avoid unexpected charges. - Supports detailed filtering and grouping of usage reports by workflow, agent, connector, or model. - Requires @cargo-ai/cli and a Cargo account with admin access.","fileCount":6,"zipByteSize":7042}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s178dcd9wkfn0a2fqrygmt3jzn87j9e1:cargo-billing","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s178dcd9wkfn0a2fqrygmt3jzn87j9e1:cargo-billing` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/cargo-ai/cargo-billing before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T11:51:48.886Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-billing/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":null},"readme":"Skill: cargo-billing\n\nOwner: cargo-ai\n\nSummary: 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\", \"add a card\", \"update my payment method\", \"why was my card declined\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.\n\nTags: latest:2.0.1\n\nVersion history:\n\nv2.0.1 | 2026-10-02T18:32:01.349Z | auto\n\ncargo-billing 2.0.1\n\n- Updated version to 2.0.1 in SKILL.md and skill-metadata.json.\n- Removed outdated skill-card.md file.\n- No functional or CLI changes; documentation and metadata update only.\n\nv2.0.0 | 2026-09-01T23:29:08.468Z | auto\n\ncargo-billing 2.0.0 — Major update with revised usage metrics and cost estimation logic.\n\n- Updated usage metrics API: `get-metrics` now returns a `metrics` array; removed `totalUsage`.\n- Added detailed documentation on the new execution-based cost model, including the 0.01-credit-per-execution charge.\n- Expanded `--unit` values to `billing.credits`, `orchestration.executions`, and `storage.records` only.\n- Improved cost estimation steps and clarified impact levers for controlling spend.\n- Cleaned up example commands and removed deprecated documentation files.\n\nv1.1.0 | 2026-08-13T03:18:22.964Z | auto\n\ncargo-billing 1.1.0\n\n- Expanded description to clarify skill triggers and use cases, with guidance on when to use alternative skills.\n- Added `update-payment-method` command for managing payment cards via CLI.\n- Improved onboarding and bootstrap instructions for new users.\n- Updated help and usage examples, including clear CLI flags and common user questions.\n- Removed deprecated `skill-card.md` file.\n\nv1.0.3 | 2026-08-11T21:44:17.427Z | auto\n\n- Updated to version 1.0.3.\n- Added skill-metadata.json and removed skill-card.md.\n- SKILL.md: Clarified compatibility requirements—sign-in now highlights `cargo-ai login --email` as an option and no longer requires browser sign-in.\n- Minor text and metadata adjustments for improved clarity.\n\nv1.0.2 | 2026-07-10T00:55:46.903Z | auto\n\n- Added a reference to the play cost attribution runbook to help users identify which node/provider dominates a play's credits spend.\n- Removed the redundant file: skill-card.md.\n- Updated version to 1.0.2.\n\nv1.0.1 | 2026-05-28T22:13:26.635Z | auto\n\n- Updated version to 1.0.1.\n- SKILL.md now references a shared prerequisites guide for install, login, and error conventions.\n- Clarified that all commands require an admin-level token; non-admin tokens result in a \"forbidden\" error.\n- Updated CLI installation instructions to use @cargo-ai/cli@latest.\n- No functional changes to commands or usage.\n\nv1.0.0 | 2026-05-28T19:28:39.970Z | auto\n\nInitial release of the cargo-billing skill.\n\n- Lets you pull usage metrics, analyze cost, and view credit consumption for your Cargo workspace using the Cargo CLI.\n- Check subscription status, invoice history, and manage billing or credits with simple CLI commands.\n- Includes quick cost estimation steps for batch runs to help avoid unexpected charges.\n- Supports detailed filtering and grouping of usage reports by workflow, agent, connector, or model.\n- Requires @cargo-ai/cli and a Cargo account with admin access.\n\nArchive index:\n\nArchive v2.0.1: 7 files, 13545 bytes\n\nFiles: references/examples/usage-metrics.md (5457b), references/response-shapes.md (4733b), references/troubleshooting.md (3144b), skill-card.md (1998b), skill-metadata.json (792b), SKILL.md (15768b), _meta.json (132b)\n\nFile v2.0.1:SKILL.md\n\n---\nname: cargo-billing\ndescription: \"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\\\", \\\"add a card\\\", \\\"update my payment method\\\", \\\"why was my card declined\\\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.\"\nversion: \"2.0.1\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use\n # alternatives: --oauth (browser) · --token (CI)\ncargo-ai whoami # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription update-payment-method --card-number --card-exp --card-cvc \ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → metrics[].items[] for that workflow (the response has one key, `metrics` — there is no `totalUsage`)\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = (credits_per_record × number_of_records) # provider actions\n + (nodes_per_record × number_of_records / 100) # execution charge\n```\n\nThe second term is the 0.01-credit-per-execution platform charge (\"The execution charge\" below). A sample run measures it for free — the record's execution count is `length(run.executions)`, or one row of `--unit orchestration.executions` for the sample window. Leave it out and every step-heavy graph is under-quoted.\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n| Cut node count — collapse chained `variables`, fold branch pairs into one `switch` | 0.01/execution × records; the only lever for a graph whose spend is steps, not providers |\n\n> 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).\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from --to \n\n# Group by dimension\ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from --to --group-by connector_uuid\ncargo-ai billing usage get-metrics --from --to --group-by integration_slug\ncargo-ai billing usage get-metrics --from --to --group-by model_uuid\ncargo-ai billing usage get-metrics --from --to --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from --to --workflow-uuid \ncargo-ai billing usage get-metrics --from --to --agent-uuid \ncargo-ai billing usage get-metrics --from --to --connector-uuid \ncargo-ai billing usage get-metrics --from --to --integration-slug \n\n# One unit at a time — the three below are the only accepted values\ncargo-ai billing usage get-metrics --from --to --unit billing.credits\ncargo-ai billing usage get-metrics --from --to --unit orchestration.executions\ncargo-ai billing usage get-metrics --from --to --unit storage.records\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n### The three usage units\n\n`--unit` takes exactly `billing.credits`, `orchestration.executions`, or `storage.records` — anything else is a `400` that lists them. **With no `--unit`, all three come back interleaved in the same `items[]` array**, and their `count` fields are not the same quantity. Read the unit off the slug:\n\n| Unit | Slugs in `items[]` | What `count` is |\n|---|---|---|\n| `billing.credits` | `integration..action.`, `native.`, `integration..chat`, `integration..extractor.` | Credits (fractional) |\n| `orchestration.executions` | `success`, `error` | **Node executions**, counted one-for-one — not credits |\n| `storage.records` | `insert` | Records written |\n\nAn unqualified call that shows `{\"slug\":\"success\",\"count\":1043}` next to `{\"slug\":\"integration.peopleDataLabs.action.queryPeople\",\"count\":174}` is reporting 1,043 *executions* beside 174 *credits*. Pass `--unit` whenever the number is going into an estimate.\n\n### The execution charge\n\n**Every node execution bills 0.01 credits — 1 credit per 100 executions.** It applies to every node kind and every node, including the structural natives that carry no provider price: `branch`, `filter`, `switch`, `split`, `group`, `variables`, `start`, `end`. There is no free step in a workflow.\n\nThis charge is **not attributed per node**. `run get` → `executions[].creditsUsedCount` and the `spans.execution_credits_used_count` column both carry the *provider* cost alone, and read `0` on a native node that nonetheless billed. Node-by-node attribution therefore under-counts every graph, and the shortfall grows with step count, not with spend.\n\nThe only surface that shows it:\n\n```bash\ncargo-ai billing usage get-metrics --from --to --unit orchestration.executions\n# → items[] = [{\"slug\":\"success\",\"count\":}, {\"slug\":\"error\",\"count\":}]\n# credits = (success + error) / 100\n```\n\nCross-check against the runtime tables, which agree row-for-row:\n\n```bash\ncargo-ai orchestration query execute \\\n \"SELECT execution_status, count() AS executions, count() / 100 AS credits\n FROM spans WHERE execution_started_at >= '' GROUP BY execution_status\"\n```\n\n**Why it matters for estimates.** A graph's cost has two terms:\n\n```\ncredits = (provider cost per record × records) + (nodes per record × records ÷ 100)\n```\n\nThe second term is invisible in the credits cost table, which prices *actions*, not *steps*. It is small next to an action-heavy play (a LinkedIn enrich on every record dwarfs its 8 steps) and dominant on step-heavy, action-light ones — a 12-node routing sweep over 20,000 records is 2,400 credits with no provider call at all. Errored executions bill too, so a graph that fails late bills its whole prefix.\n\n**Tools fan out.** A tool node is one execution *plus* every node inside the tool's own graph, each billed separately. Extracting a subgraph into a tool is a debuggability win, not a cost saving — it adds one execution per record on top of what the internals already cost. When a graph's execution count exceeds its visible node count, tool nodes are the first place to look: group by `node_slug` in `spans` to find them.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card # card on file\ncargo-ai billing subscription update-payment-method # add or replace the card (see below)\ncargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n### The free tier\n\nA 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.\n\nWhat 100 credits buys, as ballpark anchors (per-action costs in [`../cargo-gtm/references/credits-cost-table.md`](../cargo-gtm/references/credits-cost-table.md)):\n\n| Work | Cost | 100 credits ≈ |\n|---|---|---|\n| Source leads — `salesNavigator.searchLeads` | 0.2/record | ~500 leads |\n| Enrich from a LinkedIn URL + verified email — `aiArk.enrichPerson` | 0.1 | ~1,000 people |\n| Verify an email — `waterfall.verifyEmail` | 0.1 | ~1,000 checks |\n| Full contact enrichment — `waterfall.enrichContact` | 2 | ~50 contacts |\n| Find a phone — `FullEnrich.findPhone` | 6 | ~16 numbers |\n\nThe [quickstart demo](../cargo-quickstart/SKILL.md) spends about **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).\n\n### Adding a card\n\nA workspace holds exactly one card. `update-payment-method` sets it, whether or not one is already on file, and takes the details three ways.\n\n```bash\n# Card details — no browser, nothing to hand off\ncargo-ai billing subscription update-payment-method \\\n --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123\n\n# Same, but keeps the number out of shell history and the process list\necho '{\"number\":\"4242424242424242\",\"expMonth\":12,\"expYear\":2030,\"cvc\":\"123\"}' \\\n | cargo-ai billing subscription update-payment-method --card-stdin\n\n# No card details — prints a Stripe-hosted form URL and waits for the card to land\ncargo-ai billing subscription update-payment-method\n```\n\n**Prefer `--card-stdin`.** Anything passed as a flag is visible in shell history and to any process that can read the process list. Card details go from your machine straight to Stripe in exchange for a token; they never reach the Cargo API, and no output prints them.\n\n**Never invent card details, and never reuse a number from elsewhere in the conversation.** Ask the user for them, or use the no-argument form and hand them the URL.\n\nThe no-argument form is the fallback when you have no details to submit: it prints a URL that opens directly on the card form, then polls until the card changes (`--timeout`, `--poll-interval`, `--no-open`). Relay that URL to the user — it works over SSH and in sandboxes.\n\nEither way the card is verified against the issuer before it becomes the default, so a card that cannot be charged fails here rather than silently at the next renewal.\n\n| Failure | What it means | What to do |\n|---|---|---|\n| `cardDeclined` + `declineCode` | The issuer refused the verification | Read `declineCode`. On a spend-limited virtual card, `insufficient_funds` or a limit code means the budget or merchant restrictions rule us out — ask the cardholder to raise it |\n| `authenticationRequired` | The card wants 3-D Secure, which needs the cardholder present | Re-run with no arguments and hand the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a usable card | Re-check the number and expiry with the user |\n\nCard updates are rate-limited to **10 per hour per workspace** (shared with setup intents). Retrying a declined card burns that budget — fix the cause rather than looping.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n\nFile v2.0.1:_meta.json\n\n{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"2.0.1\",\n \"publishedAt\": 1790965921349\n}\n\nFile v2.0.1:references/examples/usage-metrics.md\n\n# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2026-07-25T00:00:00.000Z\",\n \"items\": [\n { \"slug\": \"integration.peopleDataLabs.action.queryPeople\", \"count\": 174, \"groupBy\": null },\n { \"slug\": \"native.modelAsk\", \"count\": 0.5, \"groupBy\": null },\n { \"slug\": \"success\", \"count\": 1043, \"groupBy\": null },\n { \"slug\": \"error\", \"count\": 32, \"groupBy\": null },\n { \"slug\": \"insert\", \"count\": 24, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n**`count` is not always credits.** Unqualified, the array interleaves all three usage units: `integration.*` / `native.*` slugs are credits, `success` / `error` are **node executions** (credits = count / 100), `insert` is records written. Isolate one with `--unit billing.credits`, `--unit orchestration.executions`, or `--unit storage.records` — the only three accepted values.\n\n## Isolate the execution charge\n\nEvery node execution bills 0.01 credits, and it is attributed to no node — this is the only place it surfaces.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2026-07-25 --to 2026-07-25 --unit orchestration.executions\n# → [{\"slug\":\"error\",\"count\":32},{\"slug\":\"success\",\"count\":1043}]\n# → 1,075 executions = 10.75 credits\n```\n\nSame day, provider spend for comparison:\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2026-07-25 --to 2026-07-25 --unit billing.credits\n# → sum of items[].count = ~276 credits\n```\n\nHere orchestration is ~4% because the day was action-heavy. On an action-light sweep the ratio inverts and executions become the largest line item. See [`../../SKILL.md`](../../SKILL.md) → \"The execution charge\".\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \n```\n\n## Filter usage to a specific agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --agent-uuid \n```\n\n## Filter usage to a specific connector\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --connector-uuid \n```\n\n## Filter usage to a specific integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --integration-slug \n```\n\n## Specify unit (credits)\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --unit credits\n```\n\n## Combine group-by with filter\n\nUsage for a specific workflow, grouped by connector.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \\\n --group-by connector_uuid\n```\n\n## Check subscription and remaining credits\n\n```bash\ncargo-ai billing subscription get\n```\n\nResponse:\n\n```json\n{\n \"subscription\": {\n \"plan\": \"self-serve\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\"\n }\n}\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n```bash\n# Invoice history (amounts in cents — divide by 100 for dollars)\ncargo-ai billing subscription get-invoices\n\n# Card on file\ncargo-ai billing subscription get-credit-card\n\n# Open Stripe portal for self-service billing\ncargo-ai billing subscription create-portal-session\n```\n\n## Compare usage across two periods\n\n```bash\n# This month\ncargo-ai billing usage get-metrics \\\n --from 2025-02-01 --to 2025-02-28\n\n# Last month\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# → Compare metrics[].items[].count values to spot trends\n```\n\n## Monthly usage report (full flow)\n\n```bash\n# 1. Overall usage\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# 2. Break down by workflow\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n\n# 3. Break down by connector\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n\n# 4. Check remaining credits\ncargo-ai billing subscription get\n```\n\nFile v2.0.1:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2026-07-25T00:00:00.000Z\",\n \"items\": [\n { \"slug\": \"integration.peopleDataLabs.action.queryPeople\", \"count\": 174, \"groupBy\": null },\n { \"slug\": \"integration.serper.action.search\", \"count\": 27.35, \"groupBy\": null },\n { \"slug\": \"native.modelAsk\", \"count\": 0.5, \"groupBy\": null },\n { \"slug\": \"success\", \"count\": 1043, \"groupBy\": null },\n { \"slug\": \"error\", \"count\": 32, \"groupBy\": null },\n { \"slug\": \"insert\", \"count\": 24, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\n**With no `--unit`, three different quantities share one `items[]` array.** In the response above, `174` is credits, `1043` is *node executions*, and `24` is records written. Identify the unit from the slug:\n\n| Slug shape | Unit | `count` is |\n|---|---|---|\n| `integration..action.`, `integration..chat`, `integration..extractor.`, `native.` | `billing.credits` | Credits (fractional) |\n| `success`, `error` | `orchestration.executions` | Node executions — **credits = count / 100** |\n| `insert` | `storage.records` | Records written |\n\n`--unit` takes exactly `billing.credits`, `orchestration.executions`, or `storage.records`; any other value returns `400` listing those three. Pass it whenever the number feeds an estimate. The execution rows reconcile one-for-one with `SELECT execution_status, count() FROM spans` in `orchestration query execute`.\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count` (units depend on the slug — see above), `metrics[].items[].groupBy`.\n\nThe response has exactly one top-level key, `metrics`. There is no `totalUsage` — sum `items[].count` yourself, within one unit.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`, `startAt`, `resetAt`.\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n## cargo-ai billing subscription get-invoices\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_...\",\n \"isPaid\": true,\n \"amount\": 9900,\n \"currency\": \"usd\",\n \"dueDate\": \"2025-02-01T00:00:00Z\",\n \"url\": \"https://...\"\n }\n ]\n}\n```\n\n**Key fields:** `id`, `isPaid` (boolean), `amount` (in cents — divide by 100 for dollars, e.g. `9900` = $99.00), `url` (link to the invoice).\n\n## cargo-ai billing subscription create-portal-session\n\n```json\n{\n \"portalSession\": {\n \"url\": \"https://billing.stripe.com/session/...\"\n }\n}\n```\n\nOpen `portalSession.url` in a browser to access the Stripe self-service billing portal.\n\n## cargo-ai billing subscription update-payment-method\n\n```json\n{\n \"ok\": true,\n \"status\": \"updated\",\n \"creditCard\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"expMonth\": 12,\n \"expYear\": 2030\n }\n}\n```\n\n**Key fields:** `creditCard` describes the card now on file — the only card data ever returned. `creditCard` is absent if the card could not be read back straight after the update; the update still succeeded.\n\nOn failure the command exits non-zero with `{\"errorMessage\": \"...\"}` plus a `reason` of `cardDeclined`, `authenticationRequired`, or `paymentMethodNotFound`. A `cardDeclined` carries the issuer's `declineCode` — see [`troubleshooting.md`](troubleshooting.md).\n\n## cargo-ai billing subscription get-credit-card\n\n```json\n{\n \"creditCard\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"expMonth\": 12,\n \"expYear\": 2030\n }\n}\n```\n\n`creditCard` is `undefined` when no card is on file — the normal state for a workspace still on the free tier.\n\nFile v2.0.1:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\n## Adding a card\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `cardDeclined` with a `declineCode` | The issuer refused the zero-amount verification | Read `declineCode`. On a spend-limited virtual card this usually means the budget or merchant restrictions exclude us — ask the cardholder to raise the limit, then retry |\n| `authenticationRequired` | The card requires 3-D Secure, which cannot be completed without the cardholder | Re-run `update-payment-method` with no arguments and give the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a card we can use | Re-check the number and expiry with the user |\n| `Rate limit exceeded` on `update-payment-method` | More than 10 card updates in an hour for this workspace | Wait for `retryAfter`. Repeatedly retrying a declined card is what exhausts this — fix the decline cause first |\n| Stripe rejects the card before Cargo sees it (`code`, `param` in the error) | The number, expiry, or CVC is malformed | The `param` field names the bad field; correct it with the user |\n| `no Stripe publishable key configured` | The Cargo environment is missing `STRIPE_PUBLIC_KEY` | Environment misconfiguration, not a user error — report it; the hosted-form flow (no arguments) still works |\n| Hosted form times out | Nobody completed the form in the window | Re-run with a longer `--timeout`, or confirm with `get-credit-card` — the card may have landed after the wait ended |\n\nFile v2.0.1:skill-card.md\n\n## Description:\n\nHelps users review Cargo credit balances, usage, subscriptions, invoices, and payment methods.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nWorkspace administrators use this skill to check Cargo spending and remaining credits, investigate usage by resource, review subscription and invoice information, and manage a payment method.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A mutable latest-version CLI has admin access to billing and payment settings.\n\nMitigation: Install only from a trusted Cargo CLI package source and pin a reviewed version before using billing commands.\n\nRisk: Entering payment-card details as command-line flags may expose them in shell history or process listings.\n\nMitigation: Prefer the hosted payment form or the CLI's standard-input option; do not place card details in command-line arguments.\n\n## Reference(s):\n\n- [Cargo Billing on ClawHub](https://clawhub.ai/cargo-ai/skills/cargo-billing)\n- [Cargo skill homepage (declared in metadata)](https://github.com/getcargohq/cargo-skills)\n- [Usage metrics examples](references/examples/usage-metrics.md)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Shell commands, Guidance]\n\n**Output Format:** [Markdown with inline shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Billing answers depend on the selected workspace and the data returned by the Cargo CLI.]\n\n## Skill Version(s):\n\n2.0.1 (source: SKILL.md frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.0.1:skill-metadata.json\n\n{\n \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n \"name\": \"cargo-billing\",\n \"version\": \"2.0.1\",\n \"documents\": [\n {\n \"path\": \"SKILL.md\",\n \"kind\": \"entrypoint\",\n \"title\": \"Cargo CLI — Billing\"\n },\n {\n \"path\": \"references/examples/usage-metrics.md\",\n \"kind\": \"example\",\n \"title\": \"Usage metrics examples\"\n },\n {\n \"path\": \"references/response-shapes.md\",\n \"kind\": \"reference\",\n \"title\": \"Response shapes\"\n },\n {\n \"path\": \"references/troubleshooting.md\",\n \"kind\": \"reference\",\n \"title\": \"Troubleshooting\"\n }\n ],\n \"contentHash\": \"fb4451b1d28d67e2e0edc2a9bd23c66bacbdea1782288f2a167eb477ed030c1e\"\n}\n\nArchive v2.0.0: 7 files, 13741 bytes\n\nFiles: references/examples/usage-metrics.md (5457b), references/response-shapes.md (4733b), references/troubleshooting.md (3144b), skill-card.md (2451b), skill-metadata.json (792b), SKILL.md (15773b), _meta.json (132b)\n\nFile v2.0.0:SKILL.md\n\n---\nname: cargo-billing\ndescription: \"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\\\", \\\"add a card\\\", \\\"update my payment method\\\", \\\"why was my card declined\\\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.\"\nversion: \"2.0.0\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use\n # alternatives: --oauth (browser) · --token (CI)\ncargo-ai whoami # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription update-payment-method --card-number --card-exp --card-cvc \ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → metrics[].items[] for that workflow (the response has one key, `metrics` — there is no `totalUsage`)\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = (credits_per_record × number_of_records) # provider actions\n + (nodes_per_record × number_of_records / 100) # execution charge\n```\n\nThe second term is the 0.01-credit-per-execution platform charge (\"The execution charge\" below). A sample run measures it for free — the record's execution count is `length(run.executions)`, or one row of `--unit orchestration.executions` for the sample window. Leave it out and every step-heavy graph is under-quoted.\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n| Cut node count — collapse chained `variables`, fold branch pairs into one `switch` | 0.01/execution × records; the only lever for a graph whose spend is steps, not providers |\n\n> 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).\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from --to \n\n# Group by dimension\ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from --to --group-by connector_uuid\ncargo-ai billing usage get-metrics --from --to --group-by integration_slug\ncargo-ai billing usage get-metrics --from --to --group-by model_uuid\ncargo-ai billing usage get-metrics --from --to --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from --to --workflow-uuid \ncargo-ai billing usage get-metrics --from --to --agent-uuid \ncargo-ai billing usage get-metrics --from --to --connector-uuid \ncargo-ai billing usage get-metrics --from --to --integration-slug \n\n# One unit at a time — the three below are the only accepted values\ncargo-ai billing usage get-metrics --from --to --unit billing.credits\ncargo-ai billing usage get-metrics --from --to --unit orchestration.executions\ncargo-ai billing usage get-metrics --from --to --unit storage.records\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n### The three usage units\n\n`--unit` takes exactly `billing.credits`, `orchestration.executions`, or `storage.records` — anything else is a `400` that lists them. **With no `--unit`, all three come back interleaved in the same `items[]` array**, and their `count` fields are not the same quantity. Read the unit off the slug:\n\n| Unit | Slugs in `items[]` | What `count` is |\n|---|---|---|\n| `billing.credits` | `integration..action.`, `native.`, `integration..chat`, `integration..extractor.` | Credits (fractional) |\n| `orchestration.executions` | `success`, `error` | **Node executions**, counted one-for-one — not credits |\n| `storage.records` | `insert` | Records written |\n\nAn unqualified call that shows `{\"slug\":\"success\",\"count\":1043}` next to `{\"slug\":\"integration.peopleDataLabs.action.queryPeople\",\"count\":174}` is reporting 1,043 *executions* beside 174 *credits*. Pass `--unit` whenever the number is going into an estimate.\n\n### The execution charge\n\n**Every node execution bills 0.01 credits — 1 credit per 100 executions.** It applies to every node kind and every node, including the structural natives that carry no provider price: `branch`, `filter`, `switch`, `split`, `group`, `variables`, `start`, `end`. There is no free step in a workflow.\n\nThis charge is **not attributed per node**. `run get` → `executions[].creditsUsedCount` and the `spans.execution_credits_used_count` column both carry the *provider* cost alone, and read `0` on a native node that nonetheless billed. Node-by-node attribution therefore under-counts every graph, and the shortfall grows with step count, not with spend.\n\nThe only surface that shows it:\n\n```bash\ncargo-ai billing usage get-metrics --from --to --unit orchestration.executions\n# → items[] = [{\"slug\":\"success\",\"count\":}, {\"slug\":\"error\",\"count\":}]\n# credits = (success + error) / 100\n```\n\nCross-check against the runtime tables, which agree row-for-row:\n\n```bash\ncargo-ai orchestration query execute \\\n \"SELECT execution_status, count() AS executions, count() / 100 AS credits\n FROM spans WHERE execution_started_at >= '' GROUP BY execution_status\"\n```\n\n**Why it matters for estimates.** A graph's cost has two terms:\n\n```\ncredits = (provider cost per record × records) + (nodes per record × records ÷ 100)\n```\n\nThe second term is invisible in the credits cost table, which prices *actions*, not *steps*. It is small next to an action-heavy play (a LinkedIn enrich on every record dwarfs its 8 steps) and dominant on step-heavy, action-light ones — a 12-node routing sweep over 20,000 records is 2,400 credits with no provider call at all. Errored executions bill too, so a graph that fails late bills its whole prefix.\n\n**Tools fan out.** A tool node is one execution *plus* every node inside the tool's own graph, each billed separately. Extracting a subgraph into a tool is a debuggability win, not a cost saving — it adds one execution per record on top of what the internals already cost. When a graph's execution count exceeds its visible node count, tool nodes are the first place to look: group by `node_slug` in `spans` to find them.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card # card on file\ncargo-ai billing subscription update-payment-method # add or replace the card (see below)\ncargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n### The free tier\n\nA 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.\n\nWhat 100 credits buys, as ballpark anchors (per-action costs in [`../cargo-gtm/references/credits-cost-table.md`](../cargo-gtm/references/credits-cost-table.md)):\n\n| Work | Cost | 100 credits ≈ |\n|---|---|---|\n| Source leads — `salesNavigator.searchLeads` | 0.02/record | ~5,000 leads |\n| Enrich from a LinkedIn URL + verified email — `aiArk.enrichPerson` | 0.1 | ~1,000 people |\n| Verify an email — `waterfall.verifyEmail` | 0.1 | ~1,000 checks |\n| Full contact enrichment — `waterfall.enrichContact` | 2 | ~50 contacts |\n| Find a phone — `FullEnrich.findPhone` | 6 | ~16 numbers |\n\nThe [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).\n\n### Adding a card\n\nA workspace holds exactly one card. `update-payment-method` sets it, whether or not one is already on file, and takes the details three ways.\n\n```bash\n# Card details — no browser, nothing to hand off\ncargo-ai billing subscription update-payment-method \\\n --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123\n\n# Same, but keeps the number out of shell history and the process list\necho '{\"number\":\"4242424242424242\",\"expMonth\":12,\"expYear\":2030,\"cvc\":\"123\"}' \\\n | cargo-ai billing subscription update-payment-method --card-stdin\n\n# No card details — prints a Stripe-hosted form URL and waits for the card to land\ncargo-ai billing subscription update-payment-method\n```\n\n**Prefer `--card-stdin`.** Anything passed as a flag is visible in shell history and to any process that can read the process list. Card details go from your machine straight to Stripe in exchange for a token; they never reach the Cargo API, and no output prints them.\n\n**Never invent card details, and never reuse a number from elsewhere in the conversation.** Ask the user for them, or use the no-argument form and hand them the URL.\n\nThe no-argument form is the fallback when you have no details to submit: it prints a URL that opens directly on the card form, then polls until the card changes (`--timeout`, `--poll-interval`, `--no-open`). Relay that URL to the user — it works over SSH and in sandboxes.\n\nEither way the card is verified against the issuer before it becomes the default, so a card that cannot be charged fails here rather than silently at the next renewal.\n\n| Failure | What it means | What to do |\n|---|---|---|\n| `cardDeclined` + `declineCode` | The issuer refused the verification | Read `declineCode`. On a spend-limited virtual card, `insufficient_funds` or a limit code means the budget or merchant restrictions rule us out — ask the cardholder to raise it |\n| `authenticationRequired` | The card wants 3-D Secure, which needs the cardholder present | Re-run with no arguments and hand the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a usable card | Re-check the number and expiry with the user |\n\nCard updates are rate-limited to **10 per hour per workspace** (shared with setup intents). Retrying a declined card burns that budget — fix the cause rather than looping.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n\nFile v2.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"2.0.0\",\n \"publishedAt\": 1788305348468\n}\n\nFile v2.0.0:references/examples/usage-metrics.md\n\n# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2026-07-25T00:00:00.000Z\",\n \"items\": [\n { \"slug\": \"integration.peopleDataLabs.action.queryPeople\", \"count\": 174, \"groupBy\": null },\n { \"slug\": \"native.modelAsk\", \"count\": 0.5, \"groupBy\": null },\n { \"slug\": \"success\", \"count\": 1043, \"groupBy\": null },\n { \"slug\": \"error\", \"count\": 32, \"groupBy\": null },\n { \"slug\": \"insert\", \"count\": 24, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n**`count` is not always credits.** Unqualified, the array interleaves all three usage units: `integration.*` / `native.*` slugs are credits, `success` / `error` are **node executions** (credits = count / 100), `insert` is records written. Isolate one with `--unit billing.credits`, `--unit orchestration.executions`, or `--unit storage.records` — the only three accepted values.\n\n## Isolate the execution charge\n\nEvery node execution bills 0.01 credits, and it is attributed to no node — this is the only place it surfaces.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2026-07-25 --to 2026-07-25 --unit orchestration.executions\n# → [{\"slug\":\"error\",\"count\":32},{\"slug\":\"success\",\"count\":1043}]\n# → 1,075 executions = 10.75 credits\n```\n\nSame day, provider spend for comparison:\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2026-07-25 --to 2026-07-25 --unit billing.credits\n# → sum of items[].count = ~276 credits\n```\n\nHere orchestration is ~4% because the day was action-heavy. On an action-light sweep the ratio inverts and executions become the largest line item. See [`../../SKILL.md`](../../SKILL.md) → \"The execution charge\".\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \n```\n\n## Filter usage to a specific agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --agent-uuid \n```\n\n## Filter usage to a specific connector\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --connector-uuid \n```\n\n## Filter usage to a specific integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --integration-slug \n```\n\n## Specify unit (credits)\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --unit credits\n```\n\n## Combine group-by with filter\n\nUsage for a specific workflow, grouped by connector.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \\\n --group-by connector_uuid\n```\n\n## Check subscription and remaining credits\n\n```bash\ncargo-ai billing subscription get\n```\n\nResponse:\n\n```json\n{\n \"subscription\": {\n \"plan\": \"self-serve\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\"\n }\n}\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n```bash\n# Invoice history (amounts in cents — divide by 100 for dollars)\ncargo-ai billing subscription get-invoices\n\n# Card on file\ncargo-ai billing subscription get-credit-card\n\n# Open Stripe portal for self-service billing\ncargo-ai billing subscription create-portal-session\n```\n\n## Compare usage across two periods\n\n```bash\n# This month\ncargo-ai billing usage get-metrics \\\n --from 2025-02-01 --to 2025-02-28\n\n# Last month\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# → Compare metrics[].items[].count values to spot trends\n```\n\n## Monthly usage report (full flow)\n\n```bash\n# 1. Overall usage\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# 2. Break down by workflow\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n\n# 3. Break down by connector\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n\n# 4. Check remaining credits\ncargo-ai billing subscription get\n```\n\nFile v2.0.0:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2026-07-25T00:00:00.000Z\",\n \"items\": [\n { \"slug\": \"integration.peopleDataLabs.action.queryPeople\", \"count\": 174, \"groupBy\": null },\n { \"slug\": \"integration.serper.action.search\", \"count\": 27.35, \"groupBy\": null },\n { \"slug\": \"native.modelAsk\", \"count\": 0.5, \"groupBy\": null },\n { \"slug\": \"success\", \"count\": 1043, \"groupBy\": null },\n { \"slug\": \"error\", \"count\": 32, \"groupBy\": null },\n { \"slug\": \"insert\", \"count\": 24, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\n**With no `--unit`, three different quantities share one `items[]` array.** In the response above, `174` is credits, `1043` is *node executions*, and `24` is records written. Identify the unit from the slug:\n\n| Slug shape | Unit | `count` is |\n|---|---|---|\n| `integration..action.`, `integration..chat`, `integration..extractor.`, `native.` | `billing.credits` | Credits (fractional) |\n| `success`, `error` | `orchestration.executions` | Node executions — **credits = count / 100** |\n| `insert` | `storage.records` | Records written |\n\n`--unit` takes exactly `billing.credits`, `orchestration.executions`, or `storage.records`; any other value returns `400` listing those three. Pass it whenever the number feeds an estimate. The execution rows reconcile one-for-one with `SELECT execution_status, count() FROM spans` in `orchestration query execute`.\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count` (units depend on the slug — see above), `metrics[].items[].groupBy`.\n\nThe response has exactly one top-level key, `metrics`. There is no `totalUsage` — sum `items[].count` yourself, within one unit.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`, `startAt`, `resetAt`.\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n## cargo-ai billing subscription get-invoices\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_...\",\n \"isPaid\": true,\n \"amount\": 9900,\n \"currency\": \"usd\",\n \"dueDate\": \"2025-02-01T00:00:00Z\",\n \"url\": \"https://...\"\n }\n ]\n}\n```\n\n**Key fields:** `id`, `isPaid` (boolean), `amount` (in cents — divide by 100 for dollars, e.g. `9900` = $99.00), `url` (link to the invoice).\n\n## cargo-ai billing subscription create-portal-session\n\n```json\n{\n \"portalSession\": {\n \"url\": \"https://billing.stripe.com/session/...\"\n }\n}\n```\n\nOpen `portalSession.url` in a browser to access the Stripe self-service billing portal.\n\n## cargo-ai billing subscription update-payment-method\n\n```json\n{\n \"ok\": true,\n \"status\": \"updated\",\n \"creditCard\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"expMonth\": 12,\n \"expYear\": 2030\n }\n}\n```\n\n**Key fields:** `creditCard` describes the card now on file — the only card data ever returned. `creditCard` is absent if the card could not be read back straight after the update; the update still succeeded.\n\nOn failure the command exits non-zero with `{\"errorMessage\": \"...\"}` plus a `reason` of `cardDeclined`, `authenticationRequired`, or `paymentMethodNotFound`. A `cardDeclined` carries the issuer's `declineCode` — see [`troubleshooting.md`](troubleshooting.md).\n\n## cargo-ai billing subscription get-credit-card\n\n```json\n{\n \"creditCard\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"expMonth\": 12,\n \"expYear\": 2030\n }\n}\n```\n\n`creditCard` is `undefined` when no card is on file — the normal state for a workspace still on the free tier.\n\nFile v2.0.0:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\n## Adding a card\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `cardDeclined` with a `declineCode` | The issuer refused the zero-amount verification | Read `declineCode`. On a spend-limited virtual card this usually means the budget or merchant restrictions exclude us — ask the cardholder to raise the limit, then retry |\n| `authenticationRequired` | The card requires 3-D Secure, which cannot be completed without the cardholder | Re-run `update-payment-method` with no arguments and give the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a card we can use | Re-check the number and expiry with the user |\n| `Rate limit exceeded` on `update-payment-method` | More than 10 card updates in an hour for this workspace | Wait for `retryAfter`. Repeatedly retrying a declined card is what exhausts this — fix the decline cause first |\n| Stripe rejects the card before Cargo sees it (`code`, `param` in the error) | The number, expiry, or CVC is malformed | The `param` field names the bad field; correct it with the user |\n| `no Stripe publishable key configured` | The Cargo environment is missing `STRIPE_PUBLIC_KEY` | Environment misconfiguration, not a user error — report it; the hosted-form flow (no arguments) still works |\n| Hosted form times out | Nobody completed the form in the window | Re-run with a longer `--timeout`, or confirm with `get-credit-card` — the card may have landed after the wait ended |\n\nFile v2.0.0:skill-card.md\n\n## Description:\n\nHelps agents understand Cargo billing, including remaining credits, usage by workflow, connector, or agent, subscription state, invoice history, and payment-method workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, operators, and workspace administrators use this skill to inspect Cargo billing usage, estimate credit consumption before larger runs, check subscription and invoice status, and guide payment-method updates.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill requires admin billing access and can expose or change billing-related workspace state.\n\nMitigation: Use it only in Cargo workspaces where admin billing access is appropriate, and confirm the active workspace before any write operation.\n\nRisk: Payment-card details can leak through chat, shell history, or process listings if entered directly as command arguments.\n\nMitigation: Prefer the hosted Stripe portal or hosted card form; if CLI entry is unavoidable, avoid command-line flags and do not retain card details.\n\nRisk: Unpinned @latest npm or npx execution can run a changed CLI release.\n\nMitigation: Use a trusted pinned Cargo CLI version where possible and review updates before installing or invoking a new release.\n\n## Reference(s):\n\n- [Cargo skills repository](https://github.com/getcargohq/cargo-skills)\n- [Cargo Billing skill page](https://clawhub.ai/cargo-ai/skills/cargo-billing)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n- [Usage metrics examples](references/examples/usage-metrics.md)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce Cargo CLI commands that return JSON billing, usage, subscription, invoice, or payment-method responses.]\n\n## Skill Version(s):\n\n2.0.0 (source: SKILL.md frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.0.0:skill-metadata.json\n\n{\n \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n \"name\": \"cargo-billing\",\n \"version\": \"2.0.0\",\n \"documents\": [\n {\n \"path\": \"SKILL.md\",\n \"kind\": \"entrypoint\",\n \"title\": \"Cargo CLI — Billing\"\n },\n {\n \"path\": \"references/examples/usage-metrics.md\",\n \"kind\": \"example\",\n \"title\": \"Usage metrics examples\"\n },\n {\n \"path\": \"references/response-shapes.md\",\n \"kind\": \"reference\",\n \"title\": \"Response shapes\"\n },\n {\n \"path\": \"references/troubleshooting.md\",\n \"kind\": \"reference\",\n \"title\": \"Troubleshooting\"\n }\n ],\n \"contentHash\": \"d5e316090aed9cd788411c1d58738f0076e1263bdfd881110fb7ad75268270d6\"\n}\n\nArchive v1.1.0: 7 files, 10950 bytes\n\nFiles: references/examples/usage-metrics.md (4067b), references/response-shapes.md (3488b), references/troubleshooting.md (3144b), skill-card.md (2354b), skill-metadata.json (792b), SKILL.md (11629b), _meta.json (132b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: cargo-billing\ndescription: \"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\\\", \\\"add a card\\\", \\\"update my payment method\\\", \\\"why was my card declined\\\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.\"\nversion: \"1.1.0\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use\n # alternatives: --oauth (browser) · --token (CI)\ncargo-ai whoami # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription update-payment-method --card-number --card-exp --card-cvc \ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → .totalUsage = credits consumed today for this workflow\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = credits_per_record × number_of_records\n```\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n\n> 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).\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from --to \n\n# Group by dimension\ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from --to --group-by connector_uuid\ncargo-ai billing usage get-metrics --from --to --group-by integration_slug\ncargo-ai billing usage get-metrics --from --to --group-by model_uuid\ncargo-ai billing usage get-metrics --from --to --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from --to --workflow-uuid \ncargo-ai billing usage get-metrics --from --to --agent-uuid \ncargo-ai billing usage get-metrics --from --to --connector-uuid \ncargo-ai billing usage get-metrics --from --to --integration-slug \n\n# Specify unit\ncargo-ai billing usage get-metrics --from --to --unit credits\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card # card on file\ncargo-ai billing subscription update-payment-method # add or replace the card (see below)\ncargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n### The free tier\n\nA 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.\n\nWhat 100 credits buys, as ballpark anchors (per-action costs in [`../cargo-gtm/references/credits-cost-table.md`](../cargo-gtm/references/credits-cost-table.md)):\n\n| Work | Cost | 100 credits ≈ |\n|---|---|---|\n| Source leads — `salesNavigator.searchLeads` | 0.02/record | ~5,000 leads |\n| Enrich from a LinkedIn URL + verified email — `aiArk.enrichPerson` | 0.1 | ~1,000 people |\n| Verify an email — `waterfall.verifyEmail` | 0.1 | ~1,000 checks |\n| Full contact enrichment — `waterfall.enrichContact` | 2 | ~50 contacts |\n| Find a phone — `FullEnrich.findPhone` | 6 | ~16 numbers |\n\nThe [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).\n\n### Adding a card\n\nA workspace holds exactly one card. `update-payment-method` sets it, whether or not one is already on file, and takes the details three ways.\n\n```bash\n# Card details — no browser, nothing to hand off\ncargo-ai billing subscription update-payment-method \\\n --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123\n\n# Same, but keeps the number out of shell history and the process list\necho '{\"number\":\"4242424242424242\",\"expMonth\":12,\"expYear\":2030,\"cvc\":\"123\"}' \\\n | cargo-ai billing subscription update-payment-method --card-stdin\n\n# No card details — prints a Stripe-hosted form URL and waits for the card to land\ncargo-ai billing subscription update-payment-method\n```\n\n**Prefer `--card-stdin`.** Anything passed as a flag is visible in shell history and to any process that can read the process list. Card details go from your machine straight to Stripe in exchange for a token; they never reach the Cargo API, and no output prints them.\n\n**Never invent card details, and never reuse a number from elsewhere in the conversation.** Ask the user for them, or use the no-argument form and hand them the URL.\n\nThe no-argument form is the fallback when you have no details to submit: it prints a URL that opens directly on the card form, then polls until the card changes (`--timeout`, `--poll-interval`, `--no-open`). Relay that URL to the user — it works over SSH and in sandboxes.\n\nEither way the card is verified against the issuer before it becomes the default, so a card that cannot be charged fails here rather than silently at the next renewal.\n\n| Failure | What it means | What to do |\n|---|---|---|\n| `cardDeclined` + `declineCode` | The issuer refused the verification | Read `declineCode`. On a spend-limited virtual card, `insufficient_funds` or a limit code means the budget or merchant restrictions rule us out — ask the cardholder to raise it |\n| `authenticationRequired` | The card wants 3-D Secure, which needs the cardholder present | Re-run with no arguments and hand the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a usable card | Re-check the number and expiry with the user |\n\nCard updates are rate-limited to **10 per hour per workspace** (shared with setup intents). Retrying a declined card burns that budget — fix the cause rather than looping.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n\nFile v1.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1786591102964\n}\n\nFile v1.1.0:references/examples/usage-metrics.md\n\n# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \n```\n\n## Filter usage to a specific agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --agent-uuid \n```\n\n## Filter usage to a specific connector\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --connector-uuid \n```\n\n## Filter usage to a specific integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --integration-slug \n```\n\n## Specify unit (credits)\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --unit credits\n```\n\n## Combine group-by with filter\n\nUsage for a specific workflow, grouped by connector.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \\\n --group-by connector_uuid\n```\n\n## Check subscription and remaining credits\n\n```bash\ncargo-ai billing subscription get\n```\n\nResponse:\n\n```json\n{\n \"subscription\": {\n \"plan\": \"self-serve\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\"\n }\n}\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n```bash\n# Invoice history (amounts in cents — divide by 100 for dollars)\ncargo-ai billing subscription get-invoices\n\n# Card on file\ncargo-ai billing subscription get-credit-card\n\n# Open Stripe portal for self-service billing\ncargo-ai billing subscription create-portal-session\n```\n\n## Compare usage across two periods\n\n```bash\n# This month\ncargo-ai billing usage get-metrics \\\n --from 2025-02-01 --to 2025-02-28\n\n# Last month\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# → Compare metrics[].items[].count values to spot trends\n```\n\n## Monthly usage report (full flow)\n\n```bash\n# 1. Overall usage\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# 2. Break down by workflow\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n\n# 3. Break down by connector\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n\n# 4. Check remaining credits\ncargo-ai billing subscription get\n```\n\nFile v1.1.0:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n },\n {\n \"date\": \"2025-01-16T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 200, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count`, `metrics[].items[].groupBy`.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`, `startAt`, `resetAt`.\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n## cargo-ai billing subscription get-invoices\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_...\",\n \"isPaid\": true,\n \"amount\": 9900,\n \"currency\": \"usd\",\n \"dueDate\": \"2025-02-01T00:00:00Z\",\n \"url\": \"https://...\"\n }\n ]\n}\n```\n\n**Key fields:** `id`, `isPaid` (boolean), `amount` (in cents — divide by 100 for dollars, e.g. `9900` = $99.00), `url` (link to the invoice).\n\n## cargo-ai billing subscription create-portal-session\n\n```json\n{\n \"portalSession\": {\n \"url\": \"https://billing.stripe.com/session/...\"\n }\n}\n```\n\nOpen `portalSession.url` in a browser to access the Stripe self-service billing portal.\n\n## cargo-ai billing subscription update-payment-method\n\n```json\n{\n \"ok\": true,\n \"status\": \"updated\",\n \"creditCard\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"expMonth\": 12,\n \"expYear\": 2030\n }\n}\n```\n\n**Key fields:** `creditCard` describes the card now on file — the only card data ever returned. `creditCard` is absent if the card could not be read back straight after the update; the update still succeeded.\n\nOn failure the command exits non-zero with `{\"errorMessage\": \"...\"}` plus a `reason` of `cardDeclined`, `authenticationRequired`, or `paymentMethodNotFound`. A `cardDeclined` carries the issuer's `declineCode` — see [`troubleshooting.md`](troubleshooting.md).\n\n## cargo-ai billing subscription get-credit-card\n\n```json\n{\n \"creditCard\": {\n \"brand\": \"visa\",\n \"last4\": \"4242\",\n \"expMonth\": 12,\n \"expYear\": 2030\n }\n}\n```\n\n`creditCard` is `undefined` when no card is on file — the normal state for a workspace still on the free tier.\n\nFile v1.1.0:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\n## Adding a card\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `cardDeclined` with a `declineCode` | The issuer refused the zero-amount verification | Read `declineCode`. On a spend-limited virtual card this usually means the budget or merchant restrictions exclude us — ask the cardholder to raise the limit, then retry |\n| `authenticationRequired` | The card requires 3-D Secure, which cannot be completed without the cardholder | Re-run `update-payment-method` with no arguments and give the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a card we can use | Re-check the number and expiry with the user |\n| `Rate limit exceeded` on `update-payment-method` | More than 10 card updates in an hour for this workspace | Wait for `retryAfter`. Repeatedly retrying a declined card is what exhausts this — fix the decline cause first |\n| Stripe rejects the card before Cargo sees it (`code`, `param` in the error) | The number, expiry, or CVC is malformed | The `param` field names the bad field; correct it with the user |\n| `no Stripe publishable key configured` | The Cargo environment is missing `STRIPE_PUBLIC_KEY` | Environment misconfiguration, not a user error — report it; the hosted-form flow (no arguments) still works |\n| Hosted form times out | Nobody completed the form in the window | Re-run with a longer `--timeout`, or confirm with `get-credit-card` — the card may have landed after the wait ended |\n\nFile v1.1.0:skill-card.md\n\n## Description:\n\nHelps agents inspect Cargo billing, credit usage, subscription status, invoice history, and payment-method workflows through the Cargo CLI.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nCargo workspace administrators and operators use this skill to answer billing and budget questions, estimate run costs, review invoices, and manage the workspace payment method with admin credentials.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill operates on Cargo workspace billing and requires admin-level billing authority.\n\nMitigation: Install only where the agent is intended to have admin billing access, and confirm the active workspace with `cargo-ai whoami` before making changes.\n\nRisk: Payment card details may be exposed if passed directly as command-line flags.\n\nMitigation: Prefer the hosted Stripe portal or `--card-stdin`, and avoid passing real card numbers in shell command arguments.\n\nRisk: Billing and usage decisions can affect workspace spend.\n\nMitigation: Check current credits and estimate usage from a sample run before triggering large batches.\n\n## Reference(s):\n\n- [Cargo skill page](https://clawhub.ai/cargo-ai/skills/cargo-billing)\n- [Cargo skills repository](https://github.com/getcargohq/cargo-skills)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n- [Usage metrics examples](references/examples/usage-metrics.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with Cargo CLI shell commands and JSON response examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Commands require the Cargo CLI and an admin-capable Cargo workspace token; payment-method updates should prefer the hosted Stripe portal or card data via stdin.]\n\n## Skill Version(s):\n\n1.1.0 (source: frontmatter, skill-metadata.json, release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.1.0:skill-metadata.json\n\n{\n \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n \"name\": \"cargo-billing\",\n \"version\": \"1.1.0\",\n \"documents\": [\n {\n \"path\": \"SKILL.md\",\n \"kind\": \"entrypoint\",\n \"title\": \"Cargo CLI — Billing\"\n },\n {\n \"path\": \"references/examples/usage-metrics.md\",\n \"kind\": \"example\",\n \"title\": \"Usage metrics examples\"\n },\n {\n \"path\": \"references/response-shapes.md\",\n \"kind\": \"reference\",\n \"title\": \"Response shapes\"\n },\n {\n \"path\": \"references/troubleshooting.md\",\n \"kind\": \"reference\",\n \"title\": \"Troubleshooting\"\n }\n ],\n \"contentHash\": \"275b57f809d1a1fd286ef259ddf3b5bab4ef76cfb4d17cad80b1905c3d67df53\"\n}\n\nArchive v1.0.3: 7 files, 7631 bytes\n\nFiles: references/examples/usage-metrics.md (4067b), references/response-shapes.md (2514b), references/troubleshooting.md (1672b), skill-card.md (2314b), skill-metadata.json (792b), SKILL.md (6577b), _meta.json (132b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: cargo-billing\ndescription: 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.\nversion: \"1.0.3\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Prerequisites\n\nSee [`../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.\n\n**Admin-only:** every command in this skill requires a token with admin access on the workspace. Non-admin tokens return `{\"errorMessage\":\"forbidden\"}`.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → .totalUsage = credits consumed today for this workflow\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = credits_per_record × number_of_records\n```\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n\n> 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).\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from --to \n\n# Group by dimension\ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from --to --group-by connector_uuid\ncargo-ai billing usage get-metrics --from --to --group-by integration_slug\ncargo-ai billing usage get-metrics --from --to --group-by model_uuid\ncargo-ai billing usage get-metrics --from --to --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from --to --workflow-uuid \ncargo-ai billing usage get-metrics --from --to --agent-uuid \ncargo-ai billing usage get-metrics --from --to --connector-uuid \ncargo-ai billing usage get-metrics --from --to --integration-slug \n\n# Specify unit\ncargo-ai billing usage get-metrics --from --to --unit credits\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card # card on file\ncargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n\nFile v1.0.3:_meta.json\n\n{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1786484657427\n}\n\nFile v1.0.3:references/examples/usage-metrics.md\n\n# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \n```\n\n## Filter usage to a specific agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --agent-uuid \n```\n\n## Filter usage to a specific connector\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --connector-uuid \n```\n\n## Filter usage to a specific integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --integration-slug \n```\n\n## Specify unit (credits)\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --unit credits\n```\n\n## Combine group-by with filter\n\nUsage for a specific workflow, grouped by connector.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \\\n --group-by connector_uuid\n```\n\n## Check subscription and remaining credits\n\n```bash\ncargo-ai billing subscription get\n```\n\nResponse:\n\n```json\n{\n \"subscription\": {\n \"plan\": \"self-serve\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\"\n }\n}\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n```bash\n# Invoice history (amounts in cents — divide by 100 for dollars)\ncargo-ai billing subscription get-invoices\n\n# Card on file\ncargo-ai billing subscription get-credit-card\n\n# Open Stripe portal for self-service billing\ncargo-ai billing subscription create-portal-session\n```\n\n## Compare usage across two periods\n\n```bash\n# This month\ncargo-ai billing usage get-metrics \\\n --from 2025-02-01 --to 2025-02-28\n\n# Last month\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# → Compare metrics[].items[].count values to spot trends\n```\n\n## Monthly usage report (full flow)\n\n```bash\n# 1. Overall usage\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# 2. Break down by workflow\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n\n# 3. Break down by connector\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n\n# 4. Check remaining credits\ncargo-ai billing subscription get\n```\n\nFile v1.0.3:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n },\n {\n \"date\": \"2025-01-16T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 200, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count`, `metrics[].items[].groupBy`.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`, `startAt`, `resetAt`.\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n## cargo-ai billing subscription get-invoices\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_...\",\n \"isPaid\": true,\n \"amount\": 9900,\n \"currency\": \"usd\",\n \"dueDate\": \"2025-02-01T00:00:00Z\",\n \"url\": \"https://...\"\n }\n ]\n}\n```\n\n**Key fields:** `id`, `isPaid` (boolean), `amount` (in cents — divide by 100 for dollars, e.g. `9900` = $99.00), `url` (link to the invoice).\n\n## cargo-ai billing subscription create-portal-session\n\n```json\n{\n \"portalSession\": {\n \"url\": \"https://billing.stripe.com/session/...\"\n }\n}\n```\n\nOpen `portalSession.url` in a browser to access the Stripe self-service billing portal.\n\nFile v1.0.3:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\nFile v1.0.3:skill-card.md\n\n## Description:\n\nPull 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.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, operators, and workspace administrators use this skill to analyze Cargo usage and credits, review subscriptions and invoices, and open billing self-service workflows through the Cargo CLI.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Billing and usage commands require admin access and can reveal subscription, invoice, credit-card, usage, and portal-session information.\n\nMitigation: Install only for users who should administer Cargo billing, verify credentials with the Cargo CLI before use, and avoid portal or workflow-run commands unless the billing or usage impact is intended.\n\nRisk: The skill depends on the external Cargo CLI package and its authentication state.\n\nMitigation: Review the Cargo CLI package source and trust posture separately when your environment requires pinned or pre-approved dependencies.\n\n## Reference(s):\n\n- [Cargo Skills Repository](https://github.com/getcargohq/cargo-skills)\n- [Usage metrics examples](references/examples/usage-metrics.md)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON response examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires the Cargo CLI and admin workspace access; commands may return billing, usage, invoice, credit-card, and portal-session data.]\n\n## Skill Version(s):\n\n1.0.3 (source: frontmatter, skill-metadata.json, server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.3:skill-metadata.json\n\n{\n \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n \"name\": \"cargo-billing\",\n \"version\": \"1.0.3\",\n \"documents\": [\n {\n \"path\": \"SKILL.md\",\n \"kind\": \"entrypoint\",\n \"title\": \"Cargo CLI — Billing\"\n },\n {\n \"path\": \"references/examples/usage-metrics.md\",\n \"kind\": \"example\",\n \"title\": \"Usage metrics examples\"\n },\n {\n \"path\": \"references/response-shapes.md\",\n \"kind\": \"reference\",\n \"title\": \"Response shapes\"\n },\n {\n \"path\": \"references/troubleshooting.md\",\n \"kind\": \"reference\",\n \"title\": \"Troubleshooting\"\n }\n ],\n \"contentHash\": \"dbcaa6e9b3cb2c27d2f125c2241cd126d8818b3583de021e53384d206cffe8eb\"\n}\n\nArchive v1.0.2: 6 files, 7022 bytes\n\nFiles: references/examples/usage-metrics.md (4067b), references/response-shapes.md (2514b), references/troubleshooting.md (1672b), skill-card.md (2133b), SKILL.md (6529b), _meta.json (132b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: cargo-billing\ndescription: 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.\nversion: \"1.0.2\"\ncompatibility: Requires @cargo-ai/cli (npm) and a Cargo account (browser sign-in via --oauth, or an API token)\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Prerequisites\n\nSee [`../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.\n\n**Admin-only:** every command in this skill requires a token with admin access on the workspace. Non-admin tokens return `{\"errorMessage\":\"forbidden\"}`.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → .totalUsage = credits consumed today for this workflow\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = credits_per_record × number_of_records\n```\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n\n> 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).\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from --to \n\n# Group by dimension\ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from --to --group-by connector_uuid\ncargo-ai billing usage get-metrics --from --to --group-by integration_slug\ncargo-ai billing usage get-metrics --from --to --group-by model_uuid\ncargo-ai billing usage get-metrics --from --to --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from --to --workflow-uuid \ncargo-ai billing usage get-metrics --from --to --agent-uuid \ncargo-ai billing usage get-metrics --from --to --connector-uuid \ncargo-ai billing usage get-metrics --from --to --integration-slug \n\n# Specify unit\ncargo-ai billing usage get-metrics --from --to --unit credits\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card # card on file\ncargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1783644946903\n}\n\nFile v1.0.2:references/examples/usage-metrics.md\n\n# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \n```\n\n## Filter usage to a specific agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --agent-uuid \n```\n\n## Filter usage to a specific connector\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --connector-uuid \n```\n\n## Filter usage to a specific integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --integration-slug \n```\n\n## Specify unit (credits)\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --unit credits\n```\n\n## Combine group-by with filter\n\nUsage for a specific workflow, grouped by connector.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \\\n --group-by connector_uuid\n```\n\n## Check subscription and remaining credits\n\n```bash\ncargo-ai billing subscription get\n```\n\nResponse:\n\n```json\n{\n \"subscription\": {\n \"plan\": \"self-serve\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\"\n }\n}\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n```bash\n# Invoice history (amounts in cents — divide by 100 for dollars)\ncargo-ai billing subscription get-invoices\n\n# Card on file\ncargo-ai billing subscription get-credit-card\n\n# Open Stripe portal for self-service billing\ncargo-ai billing subscription create-portal-session\n```\n\n## Compare usage across two periods\n\n```bash\n# This month\ncargo-ai billing usage get-metrics \\\n --from 2025-02-01 --to 2025-02-28\n\n# Last month\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# → Compare metrics[].items[].count values to spot trends\n```\n\n## Monthly usage report (full flow)\n\n```bash\n# 1. Overall usage\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# 2. Break down by workflow\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n\n# 3. Break down by connector\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n\n# 4. Check remaining credits\ncargo-ai billing subscription get\n```\n\nFile v1.0.2:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n },\n {\n \"date\": \"2025-01-16T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 200, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count`, `metrics[].items[].groupBy`.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`, `startAt`, `resetAt`.\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n## cargo-ai billing subscription get-invoices\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_...\",\n \"isPaid\": true,\n \"amount\": 9900,\n \"currency\": \"usd\",\n \"dueDate\": \"2025-02-01T00:00:00Z\",\n \"url\": \"https://...\"\n }\n ]\n}\n```\n\n**Key fields:** `id`, `isPaid` (boolean), `amount` (in cents — divide by 100 for dollars, e.g. `9900` = $99.00), `url` (link to the invoice).\n\n## cargo-ai billing subscription create-portal-session\n\n```json\n{\n \"portalSession\": {\n \"url\": \"https://billing.stripe.com/session/...\"\n }\n}\n```\n\nOpen `portalSession.url` in a browser to access the Stripe self-service billing portal.\n\nFile v1.0.2:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\nFile v1.0.2:skill-card.md\n\n## Description:
\nPull usage metrics, check subscription status, view invoices, and manage credits using the Cargo CLI.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[cargo-ai](https://clawhub.ai/user/cargo-ai)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nCargo workspace administrators and operators use this skill to inspect billing usage, subscription state, invoices, credit balances, and billing portal access through the Cargo CLI.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Billing, invoice, card-on-file, and portal-session commands can reveal sensitive workspace billing details.
\nMitigation: Use trusted Cargo CLI credentials, limit use to intended admin workflows, and review commands before running them.
\nRisk: Sample workflow-run commands used for cost estimates can consume credits.
\nMitigation: Run only small samples, check available credits before larger batches, and monitor usage during execution.
\n\n\n## Reference(s):
\n- [Cargo Billing skill page](https://clawhub.ai/cargo-ai/skills/cargo-billing)
\n- [Cargo skills homepage](https://github.com/getcargohq/cargo-skills)
\n- [Response shapes](references/response-shapes.md)
\n- [Troubleshooting](references/troubleshooting.md)
\n- [Usage metrics examples](references/examples/usage-metrics.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]
\n**Output Format:** [Markdown with inline shell commands and JSON response examples]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires the Cargo CLI and admin-level Cargo billing access.]
\n\n## Skill Version(s):
\n1.0.2 (source: evidence release metadata and skill frontmatter)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.0.1: 6 files, 7027 bytes\n\nFiles: references/examples/usage-metrics.md (4067b), references/response-shapes.md (2514b), references/troubleshooting.md (1672b), skill-card.md (2340b), SKILL.md (6284b), _meta.json (132b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: cargo-billing\ndescription: 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.\nversion: \"1.0.1\"\ncompatibility: Requires @cargo-ai/cli (npm) and a Cargo account (browser sign-in via --oauth, or an API token)\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Prerequisites\n\nSee [`../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.\n\n**Admin-only:** every command in this skill requires a token with admin access on the workspace. Non-admin tokens return `{\"errorMessage\":\"forbidden\"}`.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)\n```\n\n## Quick reference\n\n```bash\ncargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription create-portal-session\n```\n\n## Estimating cost before running a batch\n\nBefore triggering a large batch, estimate credit consumption to avoid unexpected charges.\n\n**Step 1 — Check current credit balance:**\n\n```bash\ncargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits\n```\n\n**Step 2 — Estimate cost from a sample run:**\n\nRun the workflow on a single record first and measure credits consumed:\n\n```bash\n# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → .totalUsage = credits consumed today for this workflow\n```\n\n**Step 3 — Project batch cost:**\n\n```\nestimated_cost = credits_per_record × number_of_records\n```\n\nCompare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.\n\n**Step 4 — Monitor during the batch:**\n\n```bash\n# Check running costs mid-batch\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n```\n\n**Cost levers:**\n\n| Action | Effect |\n|---|---|\n| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |\n| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |\n| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |\n| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |\n\n## Usage metrics\n\nPull credit and usage data for any time range, optionally filtered and grouped.\n\n```bash\n# Basic usage for a period\ncargo-ai billing usage get-metrics --from --to \n\n# Group by dimension\ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing usage get-metrics --from --to --group-by connector_uuid\ncargo-ai billing usage get-metrics --from --to --group-by integration_slug\ncargo-ai billing usage get-metrics --from --to --group-by model_uuid\ncargo-ai billing usage get-metrics --from --to --group-by agent_uuid\n\n# Filter by specific resource\ncargo-ai billing usage get-metrics --from --to --workflow-uuid \ncargo-ai billing usage get-metrics --from --to --agent-uuid \ncargo-ai billing usage get-metrics --from --to --connector-uuid \ncargo-ai billing usage get-metrics --from --to --integration-slug \n\n# Specify unit\ncargo-ai billing usage get-metrics --from --to --unit credits\n```\n\n`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.\n\nAvailable filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.\n\n## Subscription and credits\n\n```bash\ncargo-ai billing subscription get # current plan, credits used/available, period dates\ncargo-ai billing subscription get-invoices # invoice history (amounts in cents)\ncargo-ai billing subscription get-credit-card # card on file\ncargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get`.\n\n**Note:** Invoice amounts are returned in cents. Divide by 100 for the dollar value.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai billing usage get-metrics --help\ncargo-ai billing subscription get --help\ncargo-ai billing subscription get-invoices --help\n```\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1780006406635\n}\n\nFile v1.0.1:references/examples/usage-metrics.md\n\n# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \n```\n\n## Filter usage to a specific agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --agent-uuid \n```\n\n## Filter usage to a specific connector\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --connector-uuid \n```\n\n## Filter usage to a specific integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --integration-slug \n```\n\n## Specify unit (credits)\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --unit credits\n```\n\n## Combine group-by with filter\n\nUsage for a specific workflow, grouped by connector.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --workflow-uuid \\\n --group-by connector_uuid\n```\n\n## Check subscription and remaining credits\n\n```bash\ncargo-ai billing subscription get\n```\n\nResponse:\n\n```json\n{\n \"subscription\": {\n \"plan\": \"self-serve\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\"\n }\n}\n```\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n```bash\n# Invoice history (amounts in cents — divide by 100 for dollars)\ncargo-ai billing subscription get-invoices\n\n# Card on file\ncargo-ai billing subscription get-credit-card\n\n# Open Stripe portal for self-service billing\ncargo-ai billing subscription create-portal-session\n```\n\n## Compare usage across two periods\n\n```bash\n# This month\ncargo-ai billing usage get-metrics \\\n --from 2025-02-01 --to 2025-02-28\n\n# Last month\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# → Compare metrics[].items[].count values to spot trends\n```\n\n## Monthly usage report (full flow)\n\n```bash\n# 1. Overall usage\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n\n# 2. Break down by workflow\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n\n# 3. Break down by connector\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n\n# 4. Check remaining credits\ncargo-ai billing subscription get\n```\n\nFile v1.0.1:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 150, \"groupBy\": null },\n { \"slug\": \"ai_message\", \"count\": 42, \"groupBy\": null }\n ]\n },\n {\n \"date\": \"2025-01-16T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 200, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count`, `metrics[].items[].groupBy`.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`, `startAt`, `resetAt`.\n\nRemaining credits = `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount`.\n\n## cargo-ai billing subscription get-invoices\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_...\",\n \"isPaid\": true,\n \"amount\": 9900,\n \"currency\": \"usd\",\n \"dueDate\": \"2025-02-01T00:00:00Z\",\n \"url\": \"https://...\"\n }\n ]\n}\n```\n\n**Key fields:** `id`, `isPaid` (boolean), `amount` (in cents — divide by 100 for dollars, e.g. `9900` = $99.00), `url` (link to the invoice).\n\n## cargo-ai billing subscription create-portal-session\n\n```json\n{\n \"portalSession\": {\n \"url\": \"https://billing.stripe.com/session/...\"\n }\n}\n```\n\nOpen `portalSession.url` in a browser to access the Stripe self-service billing portal.\n\nFile v1.0.1:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\nFile v1.0.1:skill-card.md\n\n## Description:
\nPull usage metrics, check subscription status, view invoices, and manage credits using the Cargo CLI.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[cargo-ai](https://clawhub.ai/user/cargo-ai)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nCargo workspace admins and developers use this skill to inspect billing analytics, usage reports, credit consumption, subscription details, invoice history, and billing portal access for a Cargo workspace.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigation\n\nArchive v1.0.0: 6 files, 7042 bytes\n\nFiles: references/examples/usage-metrics.md (4067b), references/response-shapes.md (2514b), references/troubleshooting.md (1672b), skill-card.md (2192b), SKILL.md (6510b), _meta.json (132b)","readmeExcerpt":"Skill: cargo-billing Owner: cargo-ai Summary: 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\"","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use\n # alternatives: --oauth (browser) · --token (CI)\ncargo-ai whoami # confirm the active workspace before any write"},{"language":"bash","snippet":"cargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai connection connector list # all connectors (uuid, name, integrationSlug)\ncargo-ai storage model list # all models (uuid, name, slug)"},{"language":"bash","snippet":"cargo-ai billing usage get-metrics --from --to \ncargo-ai billing usage get-metrics --from --to --group-by workflow_uuid\ncargo-ai billing subscription get\ncargo-ai billing subscription get-invoices\ncargo-ai billing subscription update-payment-method --card-number --card-exp --card-cvc \ncargo-ai billing subscription create-portal-session"},{"language":"bash","snippet":"cargo-ai billing subscription get\n# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits"},{"language":"bash","snippet":"# Run on one record\ncargo-ai orchestration run create --workflow-uuid --data '{...}'\n# → poll to completion\n\n# Check credits used for that run\ncargo-ai billing usage get-metrics \\\n --from --to \\\n --workflow-uuid \n# → metrics[].items[] for that workflow (the response has one key, `metrics` — there is no `totalUsage`)"},{"language":"text","snippet":"estimated_cost = (credits_per_record × number_of_records) # provider actions\n + (nodes_per_record × number_of_records / 100) # execution charge"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: cargo-billing\ndescription: \"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\\\", \\\"add a card\\\", \\\"update my payment method\\\", \\\"why was my card declined\\\". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.\"\nversion: \"2.0.1\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n author: getcargo\n openclaw:\n requires:\n bins:\n - cargo-ai\n install:\n - kind: node\n package: \"@cargo-ai/cli@latest\"\n bins:\n - cargo-ai\n homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Billing\n\nBilling and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/usage-metrics.md` for usage metric and subscription examples.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use\n # alternatives: --oauth (browser) · --token (CI)\ncargo-ai whoami # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Discover resources first\n\nUsage metrics can be filtered and grouped by resource UUID. Discover them before querying.\n\n```bash\ncargo-ai orchestration play list # all plays (name, workflowUuid)\ncargo-ai orchestration tool list # all tools (name, workflowUuid)\ncargo-ai ai agent list # all agents (uuid, name)\ncargo-ai"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n \"slug\": \"cargo-billing\",\n \"version\": \"2.0.1\",\n \"publishedAt\": 1790965921349\n}"},{"path":"references/examples/usage-metrics.md","content":"# Usage metrics examples\n\n## Get overall usage for a time range\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31\n```\n\nResponse:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2026-07-25T00:00:00.000Z\",\n \"items\": [\n { \"slug\": \"integration.peopleDataLabs.action.queryPeople\", \"count\": 174, \"groupBy\": null },\n { \"slug\": \"native.modelAsk\", \"count\": 0.5, \"groupBy\": null },\n { \"slug\": \"success\", \"count\": 1043, \"groupBy\": null },\n { \"slug\": \"error\", \"count\": 32, \"groupBy\": null },\n { \"slug\": \"insert\", \"count\": 24, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\nEach item has a `slug` (usage type) and `count`. When `--group-by` is used, `groupBy` contains the resource UUID/slug.\n\n**`count` is not always credits.** Unqualified, the array interleaves all three usage units: `integration.*` / `native.*` slugs are credits, `success` / `error` are **node executions** (credits = count / 100), `insert` is records written. Isolate one with `--unit billing.credits`, `--unit orchestration.executions`, or `--unit storage.records` — the only three accepted values.\n\n## Isolate the execution charge\n\nEvery node execution bills 0.01 credits, and it is attributed to no node — this is the only place it surfaces.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2026-07-25 --to 2026-07-25 --unit orchestration.executions\n# → [{\"slug\":\"error\",\"count\":32},{\"slug\":\"success\",\"count\":1043}]\n# → 1,075 executions = 10.75 credits\n```\n\nSame day, provider spend for comparison:\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2026-07-25 --to 2026-07-25 --unit billing.credits\n# → sum of items[].count = ~276 credits\n```\n\nHere orchestration is ~4% because the day was action-heavy. On an action-light sweep the ratio inverts and executions become the largest line item. See [`../../SKILL.md`](../../SKILL.md) → \"The execution charge\".\n\n## Group by workflow\n\nSee which workflows consume the most credits.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by workflow_uuid\n# → Each item has groupBy = workflow UUID\n# → Cross-reference with: cargo-ai orchestration workflow list\n```\n\n## Group by connector\n\nSee which connectors (e.g. Salesforce, HubSpot) are used most.\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by connector_uuid\n# → Cross-reference with: cargo-ai connection connector list\n```\n\n## Group by integration\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by integration_slug\n```\n\n## Group by model\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by model_uuid\n# → Cross-reference with: cargo-ai storage model list\n```\n\n## Group by agent\n\n```bash\ncargo-ai billing usage get-metrics \\\n --from 2025-01-01 --to 2025-01-31 \\\n --group-by agent_uuid\n# → Cross-reference with: cargo-ai ai agent list\n```\n\n## Filter usage to a specific workflow\n\n"},{"path":"references/response-shapes.md","content":"# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-billing` skill.\n\n## cargo-ai billing usage get-metrics\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2026-07-25T00:00:00.000Z\",\n \"items\": [\n { \"slug\": \"integration.peopleDataLabs.action.queryPeople\", \"count\": 174, \"groupBy\": null },\n { \"slug\": \"integration.serper.action.search\", \"count\": 27.35, \"groupBy\": null },\n { \"slug\": \"native.modelAsk\", \"count\": 0.5, \"groupBy\": null },\n { \"slug\": \"success\", \"count\": 1043, \"groupBy\": null },\n { \"slug\": \"error\", \"count\": 32, \"groupBy\": null },\n { \"slug\": \"insert\", \"count\": 24, \"groupBy\": null }\n ]\n }\n ]\n}\n```\n\n**With no `--unit`, three different quantities share one `items[]` array.** In the response above, `174` is credits, `1043` is *node executions*, and `24` is records written. Identify the unit from the slug:\n\n| Slug shape | Unit | `count` is |\n|---|---|---|\n| `integration..action.`, `integration..chat`, `integration..extractor.`, `native.` | `billing.credits` | Credits (fractional) |\n| `success`, `error` | `orchestration.executions` | Node executions — **credits = count / 100** |\n| `insert` | `storage.records` | Records written |\n\n`--unit` takes exactly `billing.credits`, `orchestration.executions`, or `storage.records`; any other value returns `400` listing those three. Pass it whenever the number feeds an estimate. The execution rows reconcile one-for-one with `SELECT execution_status, count() FROM spans` in `orchestration query execute`.\n\nWhen `--group-by` is specified, `groupBy` contains the resource identifier:\n\n```json\n{\n \"metrics\": [\n {\n \"date\": \"2025-01-15T00:00:00Z\",\n \"items\": [\n { \"slug\": \"enrichment\", \"count\": 100, \"groupBy\": \"workflow-uuid-1\" },\n { \"slug\": \"enrichment\", \"count\": 50, \"groupBy\": \"workflow-uuid-2\" }\n ]\n }\n ]\n}\n```\n\n**Key fields:** `metrics[].date`, `metrics[].items[].slug` (usage type), `metrics[].items[].count` (units depend on the slug — see above), `metrics[].items[].groupBy`.\n\nThe response has exactly one top-level key, `metrics`. There is no `totalUsage` — sum `items[].count` yourself, within one unit.\n\n## cargo-ai billing subscription get\n\n```json\n{\n \"subscription\": {\n \"uuid\": \"...\",\n \"workspaceUuid\": \"...\",\n \"plan\": \"self-serve\",\n \"cadence\": \"monthly\",\n \"subscriptionStatus\": \"active\",\n \"subscriptionAvailableCreditsCount\": 10000,\n \"subscriptionCreditsUsedCount\": 3200,\n \"additionalAvailableCreditsCount\": 0,\n \"fixedPrice\": 9900,\n \"conversionRate\": 1,\n \"hasCredits\": true,\n \"startAt\": \"2025-01-01T00:00:00Z\",\n \"resetAt\": \"2025-02-01T00:00:00Z\",\n \"endAt\": null,\n \"topup\": null,\n \"createdAt\": \"2025-01-01T00:00:00Z\",\n \"updatedAt\": \"2025-01-15T00:00:00Z\"\n }\n}\n```\n\n**Key fields:** `plan` (`self-serve` or `enterprise`), `subscriptionStatus`, `subscriptionAvailableCreditsCount`, `subscriptionCreditsUsedCount`"},{"path":"references/troubleshooting.md","content":"# Troubleshooting\n\nCommon errors and recovery steps for `cargo-billing` commands.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token `; verify with `cargo-ai whoami` |\n\n## Usage metrics\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Empty metrics (no items) | Date range has no activity, or wrong format | Verify dates are `YYYY-MM-DD`; try a wider range; confirm the workspace had activity in that period |\n| `--group-by` returns items with null `groupBy` | Some usage isn't attributable to that dimension | This is expected — unattributed usage shows `groupBy: null` |\n| Metrics don't match expectations | Filtering by wrong resource UUID | Re-discover UUIDs with `play list`, `tool list`, `connector list`, or `agent list` |\n\n## Subscription and billing\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `subscription get` returns `Forbidden` | Token lacks billing permissions | Use a token with admin access; check workspace settings under **Settings > API** |\n| Invoice amounts look wrong | Amounts are in cents, not dollars | Divide `amount` by 100 for the dollar value |\n| `create-portal-session` returns an error | Subscription not active or no Stripe setup | Verify the workspace has an active paid subscription |\n\n## Adding a card\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `cardDeclined` with a `declineCode` | The issuer refused the zero-amount verification | Read `declineCode`. On a spend-limited virtual card this usually means the budget or merchant restrictions exclude us — ask the cardholder to raise the limit, then retry |\n| `authenticationRequired` | The card requires 3-D Secure, which cannot be completed without the cardholder | Re-run `update-payment-method` with no arguments and give the user the hosted-form URL |\n| `paymentMethodNotFound` | The details did not resolve to a card we can use | Re-check the number and expiry with the user |\n| `Rate limit exceeded` on `update-payment-method` | More than 10 card updates in an hour for this workspace | Wait for `retryAfter`. Repeatedly retrying a declined card is what exhausts this — fix the decline cause first |\n| Stripe rejects the card before Cargo sees it (`code`, `param` in the error) | The number, expiry, or CVC is malformed | The `param` field names the bad field; correct it with the user |\n| `no Stripe publishable key configured` | The Cargo environment is missing `STRIPE_PUBLIC_KEY` | Environment misconfiguration, not a user error — report it; the hosted-form flow (no arguments) still works |\n| Hosted form times out | Nobody completed the form in"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1965,"uniquenessScore":39,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:05:09.415Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:51:48.889Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}