# l4 tags list

> List provider and virtual tag keys with their value count, resource count, spend and share of spend.

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


`l4 tags list` prints the tag keys in your organization: the provider keys read from your cloud bills, and the virtual keys you defined. It reads `GET /api/v1/tags/keys`.

```bash
l4 tags list [flags]
```

## Flags

| Flag                              | Description                                                                |
| --------------------------------- | -------------------------------------------------------------------------- |
| `--origin <o>`                    | `virtual` or `provider`. Omit for both                                     |
| `--provider <p>`                  | `aws`, `gcp`, `azure` or `digitalocean`. Omit for every provider           |
| `--search <text>`                 | Match key names. The API runs the search, so it covers every key           |
| `--start <date>` / `--end <date>` | Window for spend and share of spend. See [Dates](/cli/commands/tags#dates) |

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

## Examples

```bash
l4 tags list
l4 tags list --origin virtual
l4 tags list --provider gcp --search team
l4 tags list --start 2026-08-01 --end 2026-08-31
l4 tags list --origin virtual --jq '.data[] | select(.status == "reprocessing") | .name'
```

## Output

Default output is a table with one row per key. Its Shadows column names the provider key a virtual key takes the place of, and reads `-` otherwise, because a key that shadows one changes what every other command reports for that name. With `--json` the whole API envelope is printed, and each row carries:

```text
.data[].id                     # vtk_... for a virtual key, ptk_... for a provider key
.data[].name
.data[].origin                 # "virtual" or "provider"
.data[].description
.data[].providers[]            # "aws", "gcp"
.data[].value_count
.data[].resource_count
.data[].spend
.data[].spend_share_pct
.data[].status                 # virtual keys: "active", "reprocessing" or "error"
.data[].shares_provider_key    # true for a virtual key named after a provider key
.data[].values[]               # .id and .name
```

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

## Related

* [`l4 tags show`](/cli/commands/tags/show): one key in full
* [`l4 tags coverage`](/cli/commands/tags/coverage): how much spend the keys cover
* [Virtual tags](/guides/virtual-tags): what a virtual key is