Cargo Billing

Cargo CLI — Billing

Billing and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.

See references/response-shapes.md for full JSON response structures.

See references/troubleshooting.md for common errors and how to fix them.

See references/examples/usage-metrics.md for usage metric and subscription examples.

Prerequisites

See `../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.

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

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 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 - 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>
# → .totalUsage = credits consumed today for this workflow

Step 3 — Project batch cost:

estimated_cost = credits_per_record × number_of_records

Compare against subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount before proceeding.

Step 4 — Monitor during the batch:

# Check running costs mid-batch
cargo-ai billing usage get-metrics \
  --from <start-date> --to <today> \
  --workflow-uuid <uuid>

Cost levers:

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>

# Specify unit
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit credits

--group-by values: workflow_uuid, connector_uuid, model_uuid, integration_slug, agent_uuid.

Available filters: --workflow-uuid, --model-uuid, --connector-uuid, --integration-slug, --slug, --agent-uuid. Combine with --group-by and --unit.

Subscription and credits

cargo-ai billing subscription get                    # current plan, credits used/available, period dates
cargo-ai billing subscription get-invoices            # invoice history (amounts in cents)
cargo-ai billing subscription get-credit-card         # card on file
cargo-ai billing subscription create-portal-session   # Stripe portal URL for self-service billing

Remaining credits = subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount from subscription get.

Note: Invoice amounts are returned in cents. Divide by 100 for the dollar value.

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

Usage metrics examples

Get overall usage for a time range

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31

Response:

{
  "metrics": [
    {
      "date": "2025-01-15T00:00:00Z",
      "items": [
        { "slug": "enrichment", "count": 150, "groupBy": null },
        { "slug": "ai_message", "count": 42, "groupBy": null }
      ]
    }
  ]
}

Each item has a slug (usage type) and count. When --group-by is used, groupBy contains the resource UUID/slug.

Group by workflow

See which workflows consume the most credits.

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by workflow_uuid
# → Each item has groupBy = workflow UUID
# → Cross-reference with: cargo-ai orchestration workflow list

Group by connector

See which connectors (e.g. Salesforce, HubSpot) are used most.

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by connector_uuid
# → Cross-reference with: cargo-ai connection connector list

Group by integration

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by integration_slug

Group by model

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by model_uuid
# → Cross-reference with: cargo-ai storage model list

Group by agent

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by agent_uuid
# → Cross-reference with: cargo-ai ai agent list

Filter usage to a specific workflow

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --workflow-uuid <uuid>

Filter usage to a specific agent

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --agent-uuid <uuid>

Filter usage to a specific connector

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --connector-uuid <uuid>

Filter usage to a specific integration

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --integration-slug <slug>

Specify unit (credits)

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --unit credits

Combine group-by with filter

Usage for a specific workflow, grouped by connector.

cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --workflow-uuid <uuid> \
  --group-by connector_uuid

Check subscription and remaining credits

cargo-ai billing subscription get

Response:

{
  "subscription": {
    "plan": "self-serve",
    "subscriptionStatus": "active",
    "subscriptionAvailableCreditsCount": 10000,
    "subscriptionCreditsUsedCount": 3200,
    "startAt": "2025-01-01T00:00:00Z",
    "resetAt": "2025-02-01T00:00:00Z"
  }
}

Remaining credits = subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount.

# Invoice history (amounts in cents — divide by 100 for dollars)
cargo-ai billing subscription get-invoices

# Card on file
cargo-ai billing subscription get-credit-card

# Open Stripe portal for self-service billing
cargo-ai billing subscription create-portal-session

Compare usage across two periods

# This month
cargo-ai billing usage get-metrics \
  --from 2025-02-01 --to 2025-02-28

# Last month
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31

# → Compare metrics[].items[].count values to spot trends

Monthly usage report (full flow)

# 1. Overall usage
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31

# 2. Break down by workflow
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by workflow_uuid

# 3. Break down by connector
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by connector_uuid

# 4. Check remaining credits
cargo-ai billing subscription get

Response shapes

JSON response structures returned by Cargo CLI commands used in the cargo-billing skill.

cargo-ai billing usage get-metrics

{
  "metrics": [
    {
      "date": "2025-01-15T00:00:00Z",
      "items": [
        { "slug": "enrichment", "count": 150, "groupBy": null },
        { "slug": "ai_message", "count": 42, "groupBy": null }
      ]
    },
    {
      "date": "2025-01-16T00:00:00Z",
      "items": [
        { "slug": "enrichment", "count": 200, "groupBy": null }
      ]
    }
  ]
}

When --group-by is specified, groupBy contains the resource identifier:

{
  "metrics": [
    {
      "date": "2025-01-15T00:00:00Z",
      "items": [
        { "slug": "enrichment", "count": 100, "groupBy": "workflow-uuid-1" },
        { "slug": "enrichment", "count": 50, "groupBy": "workflow-uuid-2" }
      ]
    }
  ]
}

Key fields: metrics[].date, metrics[].items[].slug (usage type), metrics[].items[].count, metrics[].items[].groupBy.

cargo-ai billing subscription get

{
  "subscription": {
    "uuid": "...",
    "workspaceUuid": "...",
    "plan": "self-serve",
    "cadence": "monthly",
    "subscriptionStatus": "active",
    "subscriptionAvailableCreditsCount": 10000,
    "subscriptionCreditsUsedCount": 3200,
    "additionalAvailableCreditsCount": 0,
    "fixedPrice": 9900,
    "conversionRate": 1,
    "hasCredits": true,
    "startAt": "2025-01-01T00:00:00Z",
    "resetAt": "2025-02-01T00:00:00Z",
    "endAt": null,
    "topup": null,
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-15T00:00:00Z"
  }
}

Key fields: plan (self-serve or enterprise), subscriptionStatus, subscriptionAvailableCreditsCount, subscriptionCreditsUsedCount, startAt, resetAt.

Remaining credits = subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount.

cargo-ai billing subscription get-invoices

{
  "invoices": [
    {
      "id": "inv_...",
      "isPaid": true,
      "amount": 9900,
      "currency": "usd",
      "dueDate": "2025-02-01T00:00:00Z",
      "url": "https://..."
    }
  ]
}

Key fields: id, isPaid (boolean), amount (in cents — divide by 100 for dollars, e.g. 9900 = $99.00), url (link to the invoice).

cargo-ai billing subscription create-portal-session

{
  "portalSession": {
    "url": "https://billing.stripe.com/session/..."
  }
}

Open portalSession.url in a browser to access the Stripe self-service billing portal.

Troubleshooting

Common errors and recovery steps for cargo-billing commands.

General

Usage metrics

Subscription and billing