l4 tags costs
l4 tags costs prints what each value of a key costs, with its share of the total and its split across service categories. It works on provider keys and virtual keys alike, and reports the spend that carries no value for the key on a line of its own.
l4 tags costs <key> [--provider <p>] [--start <date> --end <date>]It reads GET /api/v1/costs/by-tag, with the key as tag_key. <key> is a provider tag key's name, or a virtual key's name or vtk_ ID. A ptk_ ID is not accepted here: the server reads that parameter as a literal tag key, so an encoded ID matches nothing.
Flags
| Flag | Description |
|---|---|
--provider <p> | aws, gcp or all. Defaults to aws |
--start <date> / --end <date> | Window, as YYYY-MM-DD. Without them, the current month to date |
Global flags apply. See CLI overview.
--provider defaults to aws. A key that spans both providers, such as the Teams key in Virtual tags, reports its AWS spend alone until you pass --provider all.Examples
l4 tags costs Teams --provider all
l4 tags costs team
l4 tags costs Teams --provider all --start 2026-08-01 --end 2026-08-31
l4 tags costs Teams --provider all --jq '.data.teams[] | [.label, .total]'
l4 tags costs Teams --provider all --jq '.data.unmapped.total'Output
Default output is a table with one row per value, highest spend first, and the unassigned spend below it. With --json the whole API envelope is printed. The fields it carries:
.data.tag_key
.data.origin # provider or virtual
.data.teams[].id # the value
.data.teams[].label
.data.teams[].total
.data.teams[].total_pct # share of the total, unassigned spend included
.data.teams[].categories # .compute, .storage, .network, .database, .other
.data.unmapped.total # spend with no value for the keyteams is the API's name for the list of values, whatever the key describes. origin says which kind of key the name resolved to, which is what settles the last line: for a virtual key the table labels it Unallocated and unmapped.total is the unallocated cost; for a provider key the table labels it Untagged and the figure is the spend on lines without the tag. A virtual key shadows a provider key of the same name, so the same argument can resolve either way.
A split or cost-based config divides a line before this command reads it, so the values still add up to the total.
An unknown provider key name returns an empty list with no error, and so does a ptk_ ID. Check the name with l4 tags list when a key you expected comes back empty.
Errors
| Exit | Symptom | Cause |
|---|---|---|
4 | Authentication required | No token resolvable; run l4 auth login or set LEVELFOUR_TOKEN |
1 | 401 authentication failed | Token revoked, expired, or from the wrong environment |
1 | 422 | A date or provider the API does not accept |
Related
l4 tags show: spend per value next to the rules that assigned itl4 tags resources: the resources behind a valuel4 costs: the cost breakdown by service, region and account- Virtual tags: define the keys this command reads