cargo-billing

Cargo CLI — 請求

使用量メトリクスの取得、サブスクリプション状態の確認、請求書の表示、クレジットの管理など、請求とクレジットの管理を行います。

JSON レスポンスの完全な構造については、references/response-shapes.mdを参照してください。 よくあるエラーとその修正方法については、references/troubleshooting.mdを参照してください。 使用量メトリクスとサブスクリプションの例については、references/examples/usage-metrics.mdを参照してください。

初期設定

すでにサインインしていて（cargo-ai whoamiでワークスペースが返される場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # 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

すべてのコマンドはJSONを標準出力に出力します。失敗した場合は、{"errorMessage": "..."}を返してゼロ以外の終了コードで終了します。実行やバッチを作成するコマンドはすべて非同期です。--wait-until-finishedを渡すか、対応するgetをポーリングしてください。**管理者専用：**このスキルのすべてのコマンドには、ワークスペースで管理者アクセス権を持つトークンが必要です（billing:read権限。カード、プラン、トップアップの変更にはbilling:writeが必要です）。この権限がないトークンでは401 {"reason":"unauthorized"}が返され、CLIにはNot authenticated: unauthorizedと表示されます。これは権限の不足であり、ログインの有効期限切れではありません。スキル一式をインストールしている場合は、../cargo/references/prerequisites.mdに、CLIのバージョン指定、トークンのスコープ、管理者専用の機能が記載されています。

先にリソースを確認する

使用量メトリクスは、リソースUUIDでフィルタリングおよびグループ化できます。クエリを実行する前に、リソースを確認してください。

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)

クイックリファレンス

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

バッチ実行前のコスト見積もり

大規模なバッチを実行する前に、クレジット消費量を見積もり、予期しない請求を避けてください。

ステップ1 — 現在のクレジット残高を確認する：

cargo-ai billing subscription get
# → subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits

ステップ2 — サンプル実行からコストを見積もる：

まず、単一のレコードでワークフローを実行し、消費されたクレジットを測定します。

# 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`)

ステップ3 — バッチのコストを予測する：

estimated_cost = (credits_per_record × number_of_records)      # provider actions
               + (nodes_per_record × number_of_records / 100)  # execution charge

2つ目の項は、実行ごとに0.01クレジットのプラットフォーム料金（以下の「実行料金」）です。サンプル実行では無料で測定できます。レコードの実行数はlength(run.executions)、またはサンプル期間の--unit orchestration.executionsの1行分です。この項を含めないと、ステップ数の多いグラフでは見積もりが必ず不足します。

続行する前に、subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCountと比較してください。

ステップ4 — バッチ実行中に監視する：

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

コストを抑える方法：

アクション	効果
より安価なモデル（例：gpt-4oではなくgpt-4o-mini）を使う	AIノードのコストを大幅に削減します
グラフの早い段階にfilterノードを追加する	コストの高いコネクター呼び出しの前に、対象外のレコードをスキップします
fallbackOnFailure: falseを設定する	障害発生時に後続ノードへ進まず、実行を早期に停止します
エージェントノードのmaxStepsを減らす	レコードごとのエージェントによるツール呼び出し回数を制限します
ノード数を減らす — 連続するvariablesをまとめ、分岐のペアを1つのswitchに統合する	レコード数×0.01／実行。支出の大半がプロバイダーではなくステップにかかるグラフで使える唯一の方法です

コスト削減策を選ぶ前に、プレイの支出を最も左右するノードまたはプロバイダーを確認するには、../cargo-diagnostics/references/play-optimize-credits.mdのアトリビューション手順を参照してください。

使用量メトリクス

任意の期間のクレジットと使用量データを取得します。オプションでフィルタリングやグループ化もできます。

# 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 の値：workflow_uuid、connector_uuid、model_uuid、integration_slug、agent_uuid、user_uuid。

利用可能なフィルター：--workflow-uuid、--model-uuid、--connector-uuid、--integration-slug、--slug、--agent-uuid。--group-by や --unit と組み合わせて使用します。

メンバーごとの利用額。 --group-by user_uuid --unit billing.credits を指定すると、実行、バッチ、エージェントメッセージを開始したメンバーにクレジットが割り当てられます。割り当て機能がリリースされた2026年10月より前に記録された使用量にはユーザー情報がないため、それ以前の月はメンバーごとに分けられません。APIでは1人のメンバーに絞り込むこともできます（GET /v1/billing/usage/metrics?userUuid=<uuid>&…）。CLIには --user-uuid フラグがないため、代わりにグループ化して、そのメンバーの行を確認してください。管理者は、APIまたはウェブアプリの Settings → Users からメンバーごとの月間上限（monthlyCreditsLimit）を設定できます。詳しくは cargo-workspace-management → Users を参照してください。上限に達したメンバーは、次のUTC月まで、新たにクレジットを消費する処理が拒否されます。ワークスペースの残高に余裕があるのに、あるメンバーの実行がクレジット不足で失敗し始めた場合は、残高を疑う前に、そのメンバーの内訳を確認してください。

使用量の単位

--unit に指定できる値は billing.credits、orchestration.executions、storage.records、hosting.events のみです。それ以外を指定すると、これらの値を列挙した 400 が返されます。--unit を指定しない場合、各単位が同じ items[] 配列に混在して返され、それぞれの count フィールドは同じ量を示すとは限りません。slugから単位を読み取ってください。

単位	items[] 内の slug	count の内容
billing.credits	integration.<slug>.action.<action>、native.<action>、integration.<slug>.chat、integration.<slug>.extractor.<name>	クレジット（小数を含む）
orchestration.executions	success、error	ノードの実行回数。1回ずつカウントされ、クレジットではありません
storage.records	insert	書き込まれたレコード数

単位を指定せず {"slug":"success","count":1043} と {"slug":"integration.peopleDataLabs.action.queryPeople","count":174} が並んで返された場合、1,043 回の実行と174 クレジットが報告されています。見積もりに使う数値を取得するときは、必ず --unit を指定してください。

実行料金

ノードの実行ごとに0.01クレジットが課金されます。実行100回につき1クレジットです。 この料金は、すべての種類のノードに適用されます。プロバイダー料金が発生しない構造用のネイティブノード（branch、filter、switch、split、group、variables、start、end）も対象です。ワークフローに無料のステップはありません。

この料金はノードごとには割り当てられません。run get の executions[].creditsUsedCount と spans.execution_credits_used_count 列には、プロバイダーのコストのみが含まれます。そのため、課金対象になっているネイティブノードでも値は 0 になります。したがって、ノードごとの割り当てではすべてのグラフで使用量を過小評価し、その差は支出額ではなくステップ数に応じて大きくなります。

この料金を確認できるのは、次の場所だけです。

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

行ごとに一致するランタイムテーブルと照合してください。

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"

見積もりに関わる理由。 グラフのコストは次の2つの要素で構成されます。

credits = (provider cost per record × records) + (nodes per record × records ÷ 100)

2つ目の要素はクレジットのコストテーブルには表示されません。このテーブルが料金を示すのは、ステップではなくアクションだからです。アクションが多い実行では、アクションのコストに比べて小さくなります（すべてのレコードに対するLinkedInのエンリッチ処理なら、8ステップ分を大きく上回ります）。一方、ステップが多くアクションが少ない実行では、この要素が大きくなります。たとえば、20,000件のレコードを12ノードで振り分ける処理では、プロバイダーへの呼び出しがなくても2,400クレジットがかかります。エラーになった実行にも課金されるため、途中で失敗したグラフも、それまでに実行した全ステップ分の料金がかかります。

ツールは処理を展開します。 ツールノードは1回の実行としてカウントされるうえ、ツール自身のグラフ内にある各ノードも個別に課金されます。サブグラフをツールとして切り出すとデバッグしやすくなりますが、コスト削減にはなりません。内部処理の料金に加えて、レコードごとに1回の実行が増えます。グラフの実行回数が表示されているノード数を上回る場合は、まずツールノードを確認してください。spans で node_slug ごとにグループ化すると特定できます。

サブスクリプションとクレジット

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

残りのクレジット = subscription get から取得した subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount

注： 請求額はセント単位で返されます。ドル単位の金額にするには、100 で割ってください。

無料プラン

新しいアカウントには、100 クレジットの無料枠があり、登録済みのカードはありません。subscription get で残高がほぼ初期状態と表示された場合は、抽象的な数値ではなく、その予算を基準に費用に関する質問へ回答してください。「利用状況はどうですか？」への有用な回答は「100 クレジットの無料枠のうち、12 クレジットを使いました」です。利用を続けるかどうかをユーザーが判断する際にも、これが誠実な回答です。

100 クレジットでできることの目安（アクションごとの費用は ../cargo-gtm/references/credits-cost-table.md を参照してください）：

作業	費用	100 クレジットでできること ≈
見込み客を検索 — salesNavigator.searchLeads	0.2/件	約500件の見込み客
LinkedIn URL から検証済みメールアドレス付きで情報を補完 — aiArk.enrichPerson	0.1	約1,000人
メールアドレスを検証 — waterfall.verifyEmail	0.1	約1,000件の検証
連絡先情報を完全に補完 — waterfall.enrichContact	2	約50件の連絡先
電話番号を検索 — FullEnrich.findPhone	6	約16件の電話番号

クイックスタートデモで消費するのは約 5 クレジットです。電話番号の検索は無料枠を最も速く消費するため、電話番号は制限付きの手段です。段階的に実行する場合の費用は1件あたり3～7クレジットで、メールの約10倍です。デフォルトの処理チェーンには決して含めず、ユーザーから明示的な依頼があった場合に限り、条件を満たした見込み客のみを対象とするプランに追加してください。費用に関するルール全体は ../cargo-gtm/references/cost-discipline.md を参照してください。

カードの追加

ワークスペースに登録できるカードは1枚だけです。update-payment-method は、カードがすでに登録されているかどうかにかかわらずカードを設定でき、詳細を指定する方法は3通りあります。

# 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

--card-stdin を推奨します。 フラグとして渡した情報は、シェルの履歴や、プロセス一覧を読み取れるあらゆるプロセスから見えてしまいます。カード情報はトークンと引き換えに、お使いのマシンから Stripe に直接送信されます。Cargo API に渡されることはなく、出力にも表示されません。

カード情報を決して作り出さないでください。また、会話内の別の場所にある番号を再利用しないでください。 ユーザーにカード情報を尋ねるか、引数なしの形式を使って URL を渡してください。

引数なしの形式は、送信するカード情報がない場合の代替手段です。カード入力フォームを直接開く URL を出力し、その後、カードが変更されるまでポーリングします（--timeout、--poll-interval、--no-open）。その URL をユーザーに伝えてください。SSH 経由やサンドボックス内でも使用できます。

いずれの方法でも、カードはデフォルトに設定される前に発行元によって確認されます。そのため、決済できないカードはここでエラーとなり、次回の更新時に何も通知されずに失敗することはありません。

失敗	意味	対処方法
cardDeclined + declineCode	発行元が確認を拒否しました	declineCode を確認してください。利用額に上限のあるバーチャルカードで、insufficient_funds または上限に関するコードが表示された場合は、予算または加盟店の制限が原因です。カード名義人に上限を引き上げるよう依頼してください
authenticationRequired	カード名義人の立ち会いが必要な 3-D Secure をカードが要求しています	引数なしで再実行し、ホスト型フォームの URL をユーザーに渡してください
paymentMethodNotFound	入力された情報から利用可能なカードを特定できませんでした	ユーザーとカード番号および有効期限を再確認してください

カードの更新は、ワークスペースごとに1時間あたり10回までに制限されています（セットアップインテントと共有）。拒否されたカードを再試行すると、その回数制限を消費します。繰り返し試すのではなく、原因を解消してください。

ヘルプ

すべてのコマンドで --help を使用できます。

cargo-ai billing usage get-metrics --help
cargo-ai billing subscription get --help
cargo-ai billing subscription get-invoices --help