# l4 tags coverage

> Report the share of spend and of resources that carry a tag, from provider tags alone and with virtual tags added.

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


`l4 tags coverage` reports how much of your spend, and how many of your resources, carry a tag. It measures twice: with provider tags alone, and with virtual tags added. The gap between the two is what your virtual keys cover that the bill's own tags miss.

```bash
l4 tags coverage [--provider <p>] [--start <date> --end <date>]
```

It reads `GET /api/v1/tags/coverage`.

## Flags

| Flag                              | Description                                                      |
| --------------------------------- | ---------------------------------------------------------------- |
| `--provider <p>`                  | `aws`, `gcp`, `azure` or `digitalocean`. Omit for every provider |
| `--start <date>` / `--end <date>` | Window. See [Dates](/cli/commands/tags#dates)                    |

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

## Examples

```bash
l4 tags coverage
l4 tags coverage --provider gcp
l4 tags coverage --start 2026-08-01 --end 2026-08-31
l4 tags coverage --jq '.data.by_spend.with_virtual_pct'
```

Fail a scheduled job when tags cover less than 90 percent of spend:

```bash
pct=$(l4 tags coverage --jq '.data.by_spend.with_virtual_pct')
[ "$pct" -ge 90 ] || { echo "Tag coverage is ${pct}%"; exit 1; }
```

## Output

Default output is one row per basis, spend and resources. With `--json` the whole API envelope is printed. The fields it carries:

```text
.data.window.start
.data.window.end
.data.by_spend.total
.data.by_spend.provider_tagged
.data.by_spend.with_virtual
.data.by_spend.provider_tagged_pct
.data.by_spend.with_virtual_pct
.data.by_resource.total
.data.by_resource.provider_tagged
.data.by_resource.with_virtual
.data.by_resource.provider_tagged_pct
.data.by_resource.with_virtual_pct
```

`by_spend` sums cost and `by_resource` counts resources. Both percentages are whole numbers the server rounds once, and the untagged share is `100` minus the tagged one.

## 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 list`](/cli/commands/tags/list): spend and share per key
* [Virtual tags](/guides/virtual-tags#unallocated-cost): the cost no key assigns