# l4 tags resources

> List the resources that carry a tag key, with the value each one holds, how it got that value, and its spend.

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


`l4 tags resources` lists the resources that carry a key, one page at a time. Each row shows the value the resource holds, which step of the evaluation assigned it, and its spend over the last 30 complete days.

```bash
l4 tags resources <key> [flags]
```

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

## Flags

| Flag                             | Description                                                                |
| -------------------------------- | -------------------------------------------------------------------------- |
| `--value <name>`                 | Only resources holding this value                                          |
| `--provider <p>`                 | `aws`, `gcp`, `azure` or `digitalocean`. Omit for every provider           |
| `--search <text>`                | Filter resources by text. The API runs the search, so it covers every page |
| `--page <n>` / `--page-size <n>` | Pagination                                                                 |

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

## Examples

```bash
l4 tags resources Teams
l4 tags resources Teams --value data
l4 tags resources Teams --provider gcp --search bigquery
l4 tags resources Teams --page 2 --page-size 50
l4 tags resources Teams --jq '.data.items[] | select(.ratio < 1) | [.name, .value_name, .ratio]'
```

## Output

Default output is a table with one row per resource and value. With `--json` the whole API envelope is printed. The fields it carries:

```text
.data.items[].resource_id
.data.items[].name              # the Name tag when present, otherwise the resource ID
.data.items[].type
.data.items[].provider
.data.items[].account_id
.data.items[].value_id
.data.items[].value_name
.data.items[].value_source      # see below
.data.items[].ratio             # share of the resource's cost this value takes
.data.items[].spend
.data.pagination.total_pages
.data.pagination.has_next
```

`value_source` names the step that assigned the value:

| `value_source` | Assigned by                                                         |
| -------------- | ------------------------------------------------------------------- |
| `provider`     | The provider's own value, kept or used as the Can Override fallback |
| `collapsed`    | A collapsed key                                                     |
| `config`       | A config with one value                                             |
| `allocation`   | A split or cost-based config                                        |

A resource that a split divides appears once per value, and each row's `ratio` gives that value's share. [How LevelFour picks a value](/guides/virtual-tags#how-levelfour-picks-a-value) has the steps in order.

## 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, resolved locally against the key list        |
| `1`  | `... has no value named ...` | The key holds no value by that name. `l4 tags show` lists them    |
| `1`  | `404` `tag_not_found`        | A `vtk_` or `ptk_` ID nobody holds                                |

## Related

* [`l4 tags show`](/cli/commands/tags/show): the key's rules and spend per value
* [`l4 tags costs`](/cli/commands/tags/costs): spend per value over a chosen window
* [Pagination](/pagination): page defaults and limits