arkcli-usage

arkcli usage

CRITICAL — Before starting, you MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains the authentication gate, configuration troubleshooting, and shared security rules CRITICAL — usage stats Before executing, be sure to first use the Read tool to read references/arkcli-usage-stats.md, and do not directly call commands blindly. CRITICAL — usage plan Before executing, be sure to first use the Read tool to read references/arkcli-usage-plan.md, and do not directly call commands blindly. CRITICAL — usage plan-details Before executing, be sure to first use the Read tool to read references/arkcli-usage-plan-details.md, and do not directly call commands blindly. CRITICAL — Coding Plan / Coding Plan Team currently do not provide per-model plan details. This type of question can only use usage plan --product coding-plan(for the team version use --product coding-plan-team) to provide a quota snapshot and explicitly state the capability boundary; do not switch to running usage stats and then pass off platform / Endpoint Token statistics as Coding Plan per-model plan details. CRITICAL — For the above Coding Plan question, in this round execute usage plan and stop after explaining the boundary. Do not proactively add Endpoint / platform usage stats, because it cannot be attributed to Coding Plan plan details; only if the user, after knowing the two are different, separately and explicitly requests "also look at platform / Endpoint usage" should a new query be started. CRITICAL — usage balance Before executing, be sure to first use the Read tool to read references/arkcli-usage-balance.md, and do not directly call commands blindly. CRITICAL — usage seats Before executing, be sure to first use the Read tool to read references/arkcli-usage-seats.md, and do not directly call commands blindly.

Data freshness (be sure to check first):usage stats goes through the upstream BFF aggregation pipeline, the data has a 5–30 minute delay, and it is positioned as "daily / aggregate analysis". Do not use it for real-time budget monitoring, rate limiting, real-time alerting, or other control scenarios that require second-level precision—for such scenarios, directly read +chat / +gen and other inference command return values' .usage field (per-request, zero delay, see arkcli-chat and arkcli-gen)。

Speech model boundary: TTS / ASR / dubbing / reading / podcast / voice / real-time voice interaction, or doubao-seed-tts-* / doubao-seed-asr-* / seedasr-* and other plaza speech models, currently in arkcli only support models search discovery. Do not use usage stats --model、usage plan-details or plan/balance commands to answer speech model usage; directly state that arkcli does not support querying speech model cost or usage.

stats / plan / plan-details / balance distinction:

• stats outputs "token-billed inference usage" (any identity, 5–30 minute delay)
• plan outputs "subscription plan quota snapshot" (AgentPlan / CodingPlan personal version + team version's "what percentage have I used / when does it refresh")
• plan-details outputs "AgentPlan per-model / within-plan and outside-plan time-series call details" (AgentPlan personal version + team version, CodingPlan has no per-model endpoint)
• balance outputs "how much X is left" (balance perspective,--type free-quota / media-asset / plan choose one of three)
• seats outputs "team seatsusage admin perspective" (how much each seat used / plan percentage;is only a usage view)。seat listing / binding / assignment / API Key rotation go to arkcli-plans 's plans team seat-list / seat-assign / rotate-apikey。

User asks "how much quota is left in my plan" → plan or balance --type plan(the latter outputs more concisely); "Which model do I use the most" → Agent Plan uses plan-details, Coding Plan can only use plan to give a quota snapshot and state that per-model breakdown is not supported; "How many tokens did I use today" → stats; "How much free quota / media asset library capacity do I have left" → balance;「how much each seat used / team seat usage distribution」→ seats --with-usage(purely administrative: who is bound to which seat / list seats / assign seats / rotate key → arkcli-plans)。

Step 0 (MUST): for "my usage" queries, route by profile first

For all "my usage / how many tokens did I use / my consumption" type questions, before running any usage command, you must first go through these three steps. Otherwise you will equate "my usage" with "my endpoint usage" and miss the plan quota bucket — the main consumption of agent-plan users is in the plan, and directly usage stats --mine often data_count=0 or severely incomplete.

Core principle: first check "the plan bucket for your own profile tier", then check the endpoint bucket. profile.type determines what "your own tier" is, and the modality determines whether "that modality is within plan coverage".

1. Probe profile.type：arkcli auth whoami --format json, read the persistent Profile summary's profile.type（platform / agent-plan / agent-plan-team / coding-plan / coding-plan-team）。profile show/list/keys list may sync online and write back Key inventory or default Key, and must not be used as ordinary Usage admission; when the summary lacks fields, truthfully state that it is unknown, and do not automatically switch Profile, Key, default, or billing path.
2. Determine modality: if the user names a model/modality → only query that modality; if not named → cover all modalities (run through text / image / video each according to the table)
3. Route by (type × modality)(①→② = first plan bucket, then endpoint bucket; single cell = only query endpoint bucket):

profile.type	text model	image model	video model
agent-plan / agent-plan-team	① arkcli usage plan(+arkcli usage plan-details --start <YYYY-MM-DD>)② arkcli usage stats --start <YYYY-MM-DD> --mine	① arkcli usage plan② arkcli usage stats --start <YYYY-MM-DD> --mine	① arkcli usage plan② arkcli usage stats --start <YYYY-MM-DD> --mine
coding-plan / coding-plan-team	① arkcli usage plan② arkcli usage stats --start <YYYY-MM-DD> --mine	arkcli usage stats --start <YYYY-MM-DD> --mine(not covered by plan)	arkcli usage stats --start <YYYY-MM-DD> --mine(not covered by plan)
platform	arkcli usage stats --start <YYYY-MM-DD> --mine(no plan)	arkcli usage stats --start <YYYY-MM-DD> --mine	arkcli usage stats --start <YYYY-MM-DD> --mine

Date parameters (must read): in the table, <YYYY-MM-DD> replace with the actual date — usage stats / usage plan-details must include --start(if missing, the CLI reports required flag(s) "start" not set,will notdefault to today);usage stats 's --end default = today.Derive from natural language --start: "today" → --start=today; "yesterday" → yesterday; "last N days / the past week" → today-(N-1); "this month/last month" → fill in the interval from the start of the month to the end of the month;If the user does not specify any time word → default --start=today,--end default same as today。usage plan / usage balance no date needed. Elsewhere in this skill, when commands are abbreviated (without the arkcli prefix, or omitting --start), fill them in completely before execution.

Why it is divided this way: The Agent Plan plan comes with preset models for text generation + image generation + video generation → the main consumption of all three modalities is in the plan; the Coding Plan plan only comes with text generation → text looks at the plan, while image/video can only look at the endpoint via the platform endpoint pool; Platform has no plan → everything goes through endpoint pay-as-you-go.

Step 0 boundaries:

• Plan not subscribed (usage plan returns subscribed:false) → the plan bucket is empty, naturally falls through to usage stats --mine, no error
• CodingPlan's usage plan-details(by model time series) is not supported by the backend (see references/arkcli-usage-plan-details.md); the coding-plan text bucket can only usage plan view quota percentage, and cannot be broken down by model
• Endpoint bucket lookup, collision fallback (endpoint→apikey) see "Quick Decision" below and references/arkcli-usage-stats.md

Use Cases

• View inference usage for the current day or a specified date range (accepts 5–30 minute delay)
• View quota consumption / reset time for subscription plans (AgentPlan / CodingPlan)
• View per-model breakdown within vs outside the AgentPlan plan
• Group statistics by model, endpoint, API Key dimensions (stats)
• Analyze Token consumption trends, produce reconciliation reports
• Not applicable to speech model usage: When the user asks how much TTS / ASR / speech model was used, remaining quota, or call count, do not execute this skill, switch to arkcli-models states only marketplace discovery is supported

Business Positioning

• This skill corresponds to the "view existing call results and consumption" scenario, it is anoffline / near-real-timeanalysis entry point
• It usually occurs after two types of downstream links:
  • The Endpoint already exists, and you want to view usage by endpoint
  • The model is already being called, and you want to analyze consumption by model / API Key
  • Or: you have subscribed to a plan, and want to see how much quota remains
• It is not the entry point for creating an Endpoint, nor the entry point for trying out models
• It is not the data source for real-time budget / rate limiting / alerting—for real-time control, use per-request .usage field (see banner above)

Quick Decision

• The user asks "how much of my plan remains / what percentage is used / when does it refresh / how many plans do I have":
  • arkcli usage plan(by default probe all 4 SKUs: personal × 2 + team × 2, only subscribed buckets send usage requests)
  • arkcli usage plan --all: do not probe subscriptions, run all 4 buckets (diagnostics / Excel)
  • arkcli usage plan --product=X: skip probing, query only
  • And balance --type plan is the same data;usage plan outputs complete (with subscribed / updated_at),balance --type plan concise (remove meta fields). Generally default to usage plan, only when the user explicitly reconciles plan balance together with "free quota / media library capacity" should you use balance --type plan(running all three types together saves cognitive overhead)
• The user asks "which model do I use the most / how much is inside vs outside the plan / a certain sub-user on the team uses a lot":
  • arkcli usage plan-details(by default last 7 days Day granularity, AgentPlan personal)
  • arkcli usage plan-details --product=agent-plan-team(team edition, automatically find caller seat or explicit --seat <id>)
  • Coding Plan exception: do not execute plan-details or stats; only execute arkcli usage plan --product coding-plan(team edition uses coding-plan-team), and clarify that the result is only a quota snapshot, not this week's per-model details, then stop. When the user has not separately requested platform / Endpoint usage, do not proactively run usage stats。
• The user asks "my usage / how many tokens I used today / my endpoint consumption":
  • First go through Step 0 (top of this document) to determine profile.type + modality: agent-plan / coding-plan (text modality) mustfirstquery the plan bucket (usage plan; agent-plan additionally usage plan-details), then do the endpoint bucket below; platform, or coding-plan's image/video modality go directly to the endpoint bucket — do not equate "my usage" with "my endpoint usage"
  • If the user explicitly names a speech model or a TTS / ASR scenario → Do not keep querying usage; the current arkcli only acknowledges voice model marketplace discovery and does not support voice model usage queries
  • Volcano: First arkcli usage stats --start <YYYY-MM-DD> --mine(default endpoint dimension)
    • Return data_count > 0 → directly from totals take the total
    • Return data_count=0(the user has no Endpoint or has not called through an Endpoint recently) → immediately retry arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=apikey
    • ⛔ Forbidden to degrade to a full query without --mine full query —— whole-account data (data_count extremely large) ≠ "my usage"; must always maintain the --mine scope
• User asks "how much have I used for each APIKey":
  • Volcano: arkcli usage stats --start <YYYY-MM-DD> --mine --mine-by=apikey, from records[].AuthToken split
• User asks "how many free tokens / model free quota do I still have on my account / how much can still be stored in the media asset library":
  • arkcli usage balance --type free-quota(model free inference quota)
  • arkcli usage balance --type media-asset(asset library capacity)
• User asks "team seatshow much used / consumption per seat / plan percentage by seat" (admin usage perspective):
  • arkcli usage seats --product agent-plan-team --with-usage(list seats + AFP usage per seat)
  • without --with-usage is also fine, but only basic metadata, no usage numbers
  • Routing division of labor: this commandonlyanswers "usage" and is not responsible for seat management. "List seats / who is bound to which seat / assign seats to employees / rotate seat APIKey" all go through arkcli-plans 's plans team seat-list / seat-assign / rotate-apikey. When the Agent routes this kind of question, look at the verb first:"used / consumed / how much" stays here,"bind / list / assign / rotate" jumps over to plans.
• If the data looks wrong: first check authentication and profile, then suspect the data itself

Agent quick execution order

1. First confirm authentication status; when unsure, first check arkcli auth status
2. First do the smallest query, then gradually add time range and grouping conditions
3. When results are abnormal, first check whether the profile / region / API Key source is correct, then suspect the data itself
4. If the user wants to view usage by endpoint, it is best to first confirm that the endpoint-id is known

Common fallbacks

• Authentication error: go to ../arkcli-auth/SKILL.md
• Query scope or environment is wrong: go to ../arkcli-config/SKILL.md
• The user does not actually have an Endpoint yet and is only preparing for formal integration: go to ../arkcli-deploy/SKILL.md
• User wants to see planpricing(not usage): go to ../arkcli-pricing/SKILL.md(pricing plans to get catalog pricing,usage plan to get a quota snapshot, the two are different perspectives)
• User wants to seesettlement amount / bill / how much money was spent(not token usage): go to ../arkcli-billing/SKILL.md(the data source is the Volcano billing center, T+1 billing; usage stats is BFF inference aggregation, near real-time)
• User asks about usage or quota for voice models / TTS / ASR: go to ../arkcli-models/SKILL.md only explains that the marketplace is searchable and arkcli does not support usage queries, and does not go to pricing / billing

Command list

Command	Description
usage stats	Query inference usage (Token / request count, aggregated by day / hour, from the token-billed inference perspective)
usage plan	Query the quota snapshot of a subscription plan (AgentPlan / CodingPlan, for 5h / weekly / monthly / session periods: "how much used / how much left / when it refreshes"). By default probes all 4 SKUs
usage plan-details	Query AgentPlan Personal Edition + Team Edition Time-series call details by model / Harness (split between in-plan vs out-of-plan). Default last 7 days,--product=agent-plan-team switch to Team Edition
usage balance	Unified entry point from the balance perspective --type free-quota / media-asset / plan(model free inference quota / asset library capacity / plan balance)
usage seats	Admin perspective List all seats under an Enterprise Edition plan (SeatID / bound sub-user / billing status). Sub-user calls usually return AccessDenied

Natural language trigger phrase table

What the user says	Corresponding command
"details by model / which model is used the most / split by model dimension / time series by model / in-plan and out-of-plan by model"	arkcli usage plan-details
"coding plan details by model / coding plan in-plan and out-of-plan"	arkcli usage plan --product coding-plan, and explicitly state that only quota snapshots are supported, not time-series details by model; do not use usage stats to impersonate
"how much quota is left / balance / how much can still be used / what percentage has been used / plan quota"	arkcli usage plan or arkcli usage balance --type plan
"how much free quota is left / model free quota / free token"	arkcli usage balance --type free-quota
"AFP consumption / today's AFP / this week's AFP"	arkcli usage plan(AFP is the plan quota unit)
"my usage / how many tokens I used today / inference usage / token consumption"	arkcli usage stats --start <YYYY-MM-DD> --mine

Reference

• arkcli-deploy -- first create an Endpoint, then view usage by endpoint
• arkcli-pricing -- catalog price inquiry (pricing plans), complementary to usage plan quota snapshots
• arkcli-shared -- authentication and global parameters