cargo-billing
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.
- Installs
- 10K
- Last 24h
- +122
- Trending rank
- #1721
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-billing- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads cargo-billing automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Cargo CLI — Billing
Billing and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.
See
references/response-shapes.mdfor full JSON response structures. Seereferences/troubleshooting.mdfor common errors and how to fix them. Seereferences/examples/usage-metrics.mdfor usage metric and subscription examples.
Bootstrap
Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.
npm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use
# alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami # confirm the active workspace before any write
Every command prints JSON to stdout; failures exit non-zero with {"errorMessage": "..."}. Anything that creates a run or a batch is async — pass --wait-until-finished or poll the matching get. Admin-only: every command in this skill requires a token with admin access on the workspace (the billing:read permission; card, plan and top-up changes need billing:write). A token without it gets a 401 {"reason":"unauthorized"}, which the CLI reports as Not authenticated: unauthorized: that is a permission gap, not an expired login. When the full skill bundle is installed, ../cargo/references/prerequisites.md adds the CLI version pin, token scopes, and the admin-only surface.
Discover resources first
Usage metrics can be filtered and grouped by resource UUID. Discover them before querying.
cargo-ai orchestration play list # all plays (name, workflowUuid)
cargo-ai orchestration tool list # all tools (name, workflowUuid)
cargo-ai ai agent list # all agents (uuid, name)
cargo-ai connection connector list # all connectors (uuid, name, integrationSlug)
cargo-ai storage model list # all models (uuid, name, slug)
Quick reference
cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>
cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --group-by workflow_uuid
cargo-ai billing subscription get
cargo-ai billing subscription get-invoices
cargo-ai billing subscription update-payment-method --card-number <number> --card-exp <MM/YYYY> --card-cvc <cvc>
cargo-ai billing subscription create-portal-session
Estimating cost before running a batch
Before triggering a large batch, estimate credit consumption to avoid unexpected charges.
Step 1 — Check current credit balance:
cargo-ai billing subscription get
# → subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits
Step 2 — Estimate cost from a sample run:
Run the workflow on a single record first and measure credits consumed:
# Run on one record
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
# → poll to completion
# Check credits used for that run
cargo-ai billing usage get-metrics \
--from <today> --to <today> \
--workflow-uuid <uuid>
# → metrics[].items[] for that workflow (the response has one key, `metrics` — there is no `totalUsage`)
Step 3 — Project batch cost:
estimated_cost = (credits_per_record × number_of_records) # provider actions
+ (nodes_per_record × number_of_records / 100) # execution charge
The 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.
Compare against subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount before proceeding.
Step 4 — Monitor during the batch:
# Check running costs mid-batch
cargo-ai billing usage get-metrics \
--from <start-date> --to <today> \
--workflow-uuid <uuid>
Cost levers:
| Action | Effect |
|---|---|
Use a cheaper model (e.g. gpt-4o-mini vs gpt-4o) | Significant reduction for AI nodes |
Add filter nodes early in the graph | Skip ineligible records before expensive connector calls |
Set fallbackOnFailure: false | Stop the run early on failures instead of continuing to downstream nodes |
Reduce maxSteps on agent nodes | Limit how many tool calls an agent can make per record |
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 |
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.
Usage metrics
Pull credit and usage data for any time range, optionally filtered and grouped.
# Basic usage for a period
cargo-ai billing usage get-metrics --from <start-date> --to <end-date>
# Group by dimension
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by workflow_uuid
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by connector_uuid
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by integration_slug
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by model_uuid
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by agent_uuid
# Filter by specific resource
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --workflow-uuid <uuid>
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --agent-uuid <uuid>
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --connector-uuid <uuid>
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --integration-slug <slug>
# One unit at a time (the fourth accepted value, hosting.events, counts hosted worker events)
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit billing.credits
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit orchestration.executions
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit storage.records
--group-by values: workflow_uuid, connector_uuid, model_uuid, integration_slug, agent_uuid, user_uuid.
Available filters: --workflow-uuid, --model-uuid, --connector-uuid, --integration-slug, --slug, --agent-uuid. Combine with --group-by and --unit.
Spend per member. --group-by user_uuid --unit billing.credits attributes credits to the member who triggered the run, batch or agent message. Usage recorded before attribution shipped (October 2026) carries no user, so earlier months don't split by member. The API also filters to one member (GET /v1/billing/usage/metrics?userUuid=<uuid>&…); the CLI has no --user-uuid flag, so group and read that member's row instead. Admins can set a per-member monthly cap (monthlyCreditsLimit, from the API or Settings → Users in the web app; see cargo-workspace-management → Users). A member who reaches it has new credit-consuming work refused until the next UTC month. When a member's runs start failing for lack of credits while the workspace balance is healthy, read this breakdown for that member before blaming the balance.
The usage units
--unit takes exactly billing.credits, orchestration.executions, storage.records, or hosting.events — anything else is a 400 that lists them. With no --unit, the units come back interleaved in the same items[] array, and their count fields are not the same quantity. Read the unit off the slug:
| Unit | Slugs in items[] | What count is |
|---|---|---|
billing.credits | integration.<slug>.action.<action>, native.<action>, integration.<slug>.chat, integration.<slug>.extractor.<name> | Credits (fractional) |
orchestration.executions | success, error | Node executions, counted one-for-one — not credits |
storage.records | insert | Records written |
An 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.
The execution charge
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.
This 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.
The only surface that shows it:
cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --unit orchestration.executions
# → items[] = [{"slug":"success","count":<executions>}, {"slug":"error","count":<executions>}]
# credits = (success + error) / 100
Cross-check against the runtime tables, which agree row-for-row:
cargo-ai orchestration query execute \
"SELECT execution_status, count() AS executions, count() / 100 AS credits
FROM spans WHERE execution_started_at >= '<YYYY-MM-DD>' GROUP BY execution_status"
Why it matters for estimates. A graph's cost has two terms:
credits = (provider cost per record × records) + (nodes per record × records ÷ 100)
The 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.
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.
Subscription and credits
cargo-ai billing subscription get # current plan, credits used/available, period dates
cargo-ai billing subscription get-invoices # invoice history (amounts in cents)
cargo-ai billing subscription get-credit-card # card on file
cargo-ai billing subscription update-payment-method # add or replace the card (see below)
cargo-ai billing subscription create-portal-session # Stripe portal URL for self-service billing
Remaining credits = subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount from subscription get.
Note: Invoice amounts are returned in cents. Divide by 100 for the dollar value.
The free tier
A new account starts with 100 free credits and no card on file. When subscription get shows a fresh or near-fresh balance, answer cost questions against that budget rather than as an abstract number — "you've used 12 of your 100 free credits" is the useful answer to "how am I doing?", and it is also the honest one when the user is deciding whether to keep going.
What 100 credits buys, as ballpark anchors (per-action costs in ../cargo-gtm/references/credits-cost-table.md):
| Work | Cost | 100 credits ≈ |
|---|---|---|
Source leads — salesNavigator.searchLeads | 0.2/record | ~500 leads |
Enrich from a LinkedIn URL + verified email — aiArk.enrichPerson | 0.1 | ~1,000 people |
Verify an email — waterfall.verifyEmail | 0.1 | ~1,000 checks |
Full contact enrichment — waterfall.enrichContact | 2 | ~50 contacts |
Find a phone — FullEnrich.findPhone | 6 | ~16 numbers |
The quickstart demo 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.
Adding a card
A workspace holds exactly one card. update-payment-method sets it, whether or not one is already on file, and takes the details three ways.
# Card details — no browser, nothing to hand off
cargo-ai billing subscription update-payment-method \
--card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123
# Same, but keeps the number out of shell history and the process list
echo '{"number":"4242424242424242","expMonth":12,"expYear":2030,"cvc":"123"}' \
| cargo-ai billing subscription update-payment-method --card-stdin
# No card details — prints a Stripe-hosted form URL and waits for the card to land
cargo-ai billing subscription update-payment-method
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.
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.
The 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.
Either 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.
| Failure | What it means | What to do |
|---|---|---|
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 |
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 |
paymentMethodNotFound | The details did not resolve to a usable card | Re-check the number and expiry with the user |
Card 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.
Help
Every command supports --help:
cargo-ai billing usage get-metrics --help
cargo-ai billing subscription get --help
cargo-ai billing subscription get-invoices --help
FAQ
What does the cargo-billing skill do?
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.
How do I install cargo-billing?
Run npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-billing in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cargo-billing/ (personal) or .claude/skills/cargo-billing/ (project).
Which AI agents can use cargo-billing?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is cargo-billing safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains cargo-billing?
It is published by getcargohq in getcargohq/cargo-skills. It has 9,993 recorded installs.
More from getcargohq/cargo-skills
cargo-connection
getcargohq/cargo-skills
Connect Cargo to an external system and find out what it can do — authenticate connectors, browse the integration catalog, and resolve the connectorUuid and actionSlug a workflow node needs. Triggers: "connect my HubSpot", "is Salesforce connected", "what integrations do you support", "can Cargo talk to ", "what actions does have", "I need the connector UUID", "set up the API key for", "it is asking for credentials again", "why is this connector failing auth", "list my connectors". Integrations: amplemarket, amplitude, attio, bigQuery, calendly, cargoSignals, closecom, contrast, csv, customerio, dbt, emailBison, expandi, googleAds, googleCalendar, googleSheets, heyReach, http, hubspot, hubspotMcp, instantly, instantlyV2, intercom, jira, kitt, lemlist, lgm, linkedinAds, linkedinMatchedAudience, livestorm, manus, marketo, metaAds, metabase, microsoftTeams, mixpanel, monaco, netsuite, netsuiteSoap, nooks, notionMcp, octave, onesignal, outreach, pipedrive, postgresql,
cargo-gtm
getcargohq/cargo-skills
Do business-to-business go-to-market work on Cargo — research accounts and buying committees, enrich and verify B2B contact records from licensed data providers, score and qualify leads, draft permission-based outreach for the user's own sequencer, sync to CRM, and monitor buying signals. Consent basis, suppression lists, and volume limits gate every step that touches a person (references/acceptable-use.md); bulk unsolicited messaging, purchased or scraped lists, and consumer targeting are refused. Triggers: "build me a list of", "find 50 at ", "who works at", "find work emails for these accounts", "enrich this CSV", "verify these emails", "build a TAM", "who fits our ICP", "who actually buys from us", "what data points should we collect on accounts", "our outbound is reaching the wrong people", "score these leads", "write a first-touch email", "push these to my CRM", "who changed jobs", "who just raised funding", "companies using ", "who is hiring ", "fi
cargo-ai
getcargohq/cargo-skills
Build and configure AI agents inside Cargo — create an agent, choose its model and temperature, write its prompt, attach knowledge for retrieval (RAG), connect MCP tool servers, manage memories, and deploy releases. Triggers: "create an agent", "make an agent that", "give the agent our docs", "attach this knowledge base", "attach this library to the agent", "add resources to the agent release", "connect an MCP server", "expose our tools as an MCP server", "use Cargo from Claude Desktop or ChatGPT", "change the agent model", "what does the agent remember", "deploy the agent", "the agent is answering wrong". Skip when: uploading the knowledge files themselves — use cargo-content; sending the agent a message or running it over records — use cargo-orchestration.
cargo-workspace-management
getcargohq/cargo-skills
Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: "invite my teammate", "create an API token for CI", "who has access", "organize these into folders", "rotate that token", "upload this CSV for a batch" — and for feedback: "report this bug to Cargo", "send feedback to the Cargo team", "this CLI command is broken", "share this session with Cargo", "request a feature". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.
cargo-orchestration
getcargohq/cargo-skills
Make Cargo actually run something, or show what it would run — execute one connector action, run a multi-step workflow, trigger a batch across a whole segment or model, message an AI agent, build or edit a node graph, draw a workflow, tool or play as a diagram, and query the runtime tables (runs, batches, spans, records) with SQL. Triggers: "run this on all my contacts", "execute the action", "kick off a batch", "build a workflow", "schedule a play", "make it run every morning", "ask the agent", "show me the workflow", "what does this tool do", "visualize this play", "draw the graph", "explain this workflow", "how many runs failed today", "what is the output schema for this action", "add a step that". Skip when: explaining why a run misbehaved — use cargo-diagnostics; downloading result files — use cargo-analytics; committing the workflow as code — use cargo-project.
cargo-analytics
getcargohq/cargo-skills
Get data out of Cargo and measure what ran — download a run output, export a segment or model to CSV or JSON, and pull run and batch success and error counts. Triggers: "download the results", "export this to CSV", "give me the file", "how many succeeded", "what is my error rate", "send me the enriched list", "get the output of that run", "how many records did it write". Skip when: asking why something failed or where credits went — use cargo-diagnostics; asking about credits, plans, or invoices — use cargo-billing.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.