arkcli-billing

arkcli billing

MUST read before execution ../arkcli-shared/SKILL.md (authentication / global rules) and references/arkcli-billing-list.md (parameter details).

Applicable scenarios

Query split billing details for a certain billing period month or month range (settlement amount / Token usage)
Filter split billing lines by Endpoint, API Key, product code, billing type
Monthly / quarterly / annual reconciliation
Troubleshoot "how much did this EP / this key spend"

Business positioning — billing vs usage stats

Dimension	`usage stats`	`billing list`
Data source	ARK BFF inference aggregation	Volcano Billing Center split billing
Timeliness	5–30 minute delay	T+1 billing
Unit	Token / request count	CNY amount

Want to see "how many tokens were used" → arkcli-usage; want to see "how much money was spent" → this skill.

Step 0 (MUST): For "my bill", first route by profile

Same as arkcli-usage 's Step 0(canonical principle) — first query "the subscription bill for your own profile tier", then query the endpoint bill. Before querying any "I...spent how much", you must go through:

Detect profile.type：arkcli auth whoami --format json, read the persistent Profile summary's profile.type。profile show/list/keys list may sync online and write back the Key, and cannot be used as ordinary Billing admission; when fields are missing, truthfully state that they are unknown, and do not automatically switch Profile, Key, default, or billing path
Determine modality: user names a model/modality → query only that modality; no naming → cover all modalities
Route by (type × modality)(①→② = first subscription bill, then endpoint bill; single cell = query only endpoint bill):

profile.type	text	image / video
`agent-plan` / `agent-plan-team`	① `arkcli billing list --start <YYYY-MM> --product ark_subscription`② `arkcli billing list --start <YYYY-MM> --mine`	Same as text (all modalities first subscription, then endpoint)
`coding-plan` / `coding-plan-team`	① `arkcli billing list --start <YYYY-MM> --product ark_subscription`② `arkcli billing list --start <YYYY-MM> --mine`	`arkcli billing list --start <YYYY-MM> --mine`(not covered by subscription)
`platform`	`arkcli billing list --start <YYYY-MM> --mine`(no subscription)	`arkcli billing list --start <YYYY-MM> --mine`

Basis same as usage: Agent Plan subscription covers three modalities, Coding Plan subscription covers only text, Platform has no subscription. Subscription bills go through the subscription category and must explicitly --product ark_subscription(the default scope does not include subscriptions, see "Agent key discipline" below); endpoint bill --mine 's empty-hit fallback is below.Each billing list must include --start <YYYY-MM>(month unit, if omitted report --start is required; to query a multi-month range add --end <YYYY-MM>)。

Quick decision

User asks	Command
Ihow much did I spend this month / last month (including "I" semantics)	First go through Step 0 (top of this document): plan profile (agent / coding-text) first `arkcli billing list --start <YYYY-MM> --product ark_subscription` subscription bill, then `arkcli billing list --start <YYYY-MM> --mine` endpoint bill; platform or non-covered modality directly `arkcli billing list --start 2026-05 --mine` — for empty-hit fallback flow see below
How much did the whole account spend / company account / overall (no subject self-reference)	`arkcli billing list --start 2026-05` (account dimension full volume)
How much did this EP spend	`arkcli billing list --start 2026-05 --endpoint ep-...`
How much did this key cost	`arkcli billing list --start 2026-05 --apikey ark-...`
How much did each EP / key under the account cost	`--split-dim endpoint` or `--split-dim apikey`
Daily / per-transaction billing details	`--interval day` with `--day YYYY-MM-DD`, or `--interval detail`
Reconciliation over the past N months	`--start ... --end ...` (closed interval, up to 24 months)
View Agent Plan / Coding Plan subscription bills	Explicit `--product ark_subscription` (default query does not include)

`--mine` fallback flow (aligned with usage stats)

When the user asks "I...how much did I spend":

Volcano: First arkcli billing list --start <YYYY-MM> --mine(default --mine-by=endpoint)
- has data → use partial_failures check truncation, then tell the user the total amount
- hits empty (no endpoints owned by current sub-user) → retry immediately --mine --mine-by=apikey
- still hits empty → report to the user "this sub-user has zero resources under this account; the bill may have been generated by the main account / other sub-users", ask whether to switch to the main account or change profile
- ⛔ Forbidden to degrade to a full query without --mine full query — full-account amount ≠ "what I spent", once --mine is lost the scope semantics go off track (aligned with arkcli-usage's same clause)

Fallback between dims (endpoint→apikey) agent can retry automatically, because the same mine semantics, does not change the query scope; butmust not drop --mine to fall back to full(that changes semantics).

Key Agent Discipline

is_truncated=true stop and ask the user, do not decide automatically — hitting the cap (in preflight mode items are not returned, only metadata + partial_failures + stderr warning) is a scale signal, not an error. First report total_records and partial_failures[*].total to the user, list the 4 options,wait for the user to explicitly choose one before continuing. Which one to choose depends on the user's current task intent (reconciliation / troubleshooting / export); the agent should not decide for the user.Never sum items as the total(items may be empty or partial):
- Want full details → --output FILE (write to disk so stdout does not explode; automatically relaxes the cap to 300k rows)
- Only need the total amount → --split-dim apikey|endpoint (server-side aggregation to a few dozen rows)
- Narrow to one resource → --endpoint <ep-...> / --apikey <ark-...>
- force streaming into stdout → --page-limit=N (for N see partial_failures.reason suggestion; mind context size)
--limit/--offset during fan-out it is N rows per fan-out (--end across months or --mine with multiple resources), partial_failures marked reason="windowed sample", so the agent knows returned ≤ limit × fanout_count
Amounts are CNY strings — JSON number precision is lossy, use a decimal library for addition / comparison, do not parseFloat
At the start of the month, reconcile the previous complete billing period — T+1 billing; the current month's current-day data is incomplete
--mine ≠ PayerID — --mine Filter resources by IAM sub-user,PayerID is the finance hosting owner account ID; in a single-account scenario manually PayerID is a no-op (= full account query). Default --mine-by=endpoint(infra ownership, aligned with usage stats); to see cost causation (my key is spending) explicitly --mine-by=apikey
Default scope = ARK inference / Agent, 9 products that support API Key cost allocation (does not include ark_subscription, to see subscription-type explicit --product ark_subscription) + profile.project auto-injection (if profile.project is a concrete id such as auto-test, automatically filter by project;default/account all-resources sentinel/empty skip = true account full; stderr outputs a soft hint). To force account full, pass --project= (empty value clears the default)

Common degradations

Authentication error / SSO expired → ../arkcli-auth/SKILL.md
Want to see inference volume (tokens / request count) → ../arkcli-usage/SKILL.md
Want to see model / plan price catalog → ../arkcli-pricing/SKILL.md

Command list

Command	Description
`billing list`	Split bill detail query (settlement amount × Token usage)