# l4 tags show

> Print one tag key. For a virtual key, its collapsed keys and configs in evaluation order, spend per value, unallocated spend, dependent keys and the latest reprocessing job.

Source: https://docs.levelfour.ai/cli/commands/tags/show


`l4 tags show` prints one tag key. For a virtual key, that is its collapsed keys and configs in the order LevelFour evaluates them, next to the spend each value took, the spend nothing matched, the keys that read this one, and the latest reprocessing job. For a provider key, it prints the values and their spend.

```bash
l4 tags show <key> [--start <date> --end <date>]
```

It reads `GET /api/v1/tags/keys/{key_id}`. `<key>` is an ID or a name, as [Naming a key](/cli/commands/tags#naming-a-key) describes.

## Flags

| Flag                              | Description                                             |
| --------------------------------- | ------------------------------------------------------- |
| `--start <date>` / `--end <date>` | Window for spend. See [Dates](/cli/commands/tags#dates) |

Global flags apply. See [CLI overview](/cli#global-flags).

## Examples

```bash
l4 tags show Teams
l4 tags show vtk_3f9a1c
l4 tags show team --start 2026-08-01 --end 2026-08-31
l4 tags show Teams --json
l4 tags show Teams --jq '.data.values[] | select(.spend > 1000) | .name'
```

## Output

Default output prints the key's settings, its rules in order, and a table of values with their spend. With `--json` the whole API envelope is printed. The fields it carries:

```text
.data.id
.data.name
.data.origin                 # "virtual" or "provider"
.data.description
.data.providers[]
.data.status                 # "active", "reprocessing" or "error"
.data.can_override
.data.effective_from         # "YYYY-MM"
.data.rules_version
.data.collapsed_keys[]       # in evaluation order, each with .position
.data.configs[]              # in evaluation order: .id, .position, .assign, .filter, .time_frame
.data.values[]               # .id, .name, .spend, .resource_count
.data.total_spend
.data.unallocated_spend
.data.resource_count
.data.dependents[]           # keys that read this one: .id, .name
.data.job                    # the latest reprocessing job, or null
.data.window.start
.data.window.end
```

`--json` prints configs as the API stores them. `assign` holds the value, the split or the cost-based source, and `filter.rules[].conditions[]` holds what a [tag file](/cli/commands/tags/apply#file-format) calls `where`.

## Reprocessing jobs

After a change, `.data.job` describes the run that reprocesses the key's costs:

```text
.data.job.id
.data.job.status             # "queued", "running", "succeeded", "failed" or "superseded"
.data.job.from_period        # "YYYY-MM"
.data.job.to_period
.data.job.periods_done
.data.job.periods_total
.data.job.error
.data.job.created_at
.data.job.finished_at
```

A `superseded` job gave way to a newer change, and the newer job carries on from there. Follow a run:

```bash
l4 tags show Teams --jq '.data.job | "\(.status) \(.periods_done)/\(.periods_total)"'
```

> **Success**
>
> `.data.status` back at `active`, with `.data.job.status` at `succeeded`, means every month from `effective_from` carries the current rules.

## 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`  | `no tag key named ...`      | A name nobody holds. The CLI resolves names against the key list before it asks for the key |
| `1`  | `404` `tag_not_found`       | A `vtk_` or `ptk_` ID nobody holds in this organization                                     |

## Related

* [`l4 tags resources`](/cli/commands/tags/resources): the resources behind each value
* [`l4 tags apply`](/cli/commands/tags/apply): change the definition
* [Virtual tags](/guides/virtual-tags#how-levelfour-picks-a-value): the order the rules run in