---
title: NerdGraph tutorial: View and add tags
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-tagging-api-tutorial
---

You can use our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) to add [tags](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/tagging-use-tags-organize-group-what-you-monitor) to your data to help improve data organization and findability.

## Overview [#overview]

This doc explains how to use our NerdGraph API to add and manage tags. Note that this is only one way to add tags. For other methods, see [How tags are added](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/use-tags-help-organize-find-your-data/#tag-sources). For how to automate tags using our CLI tool, see our [developer site](https://developer.newrelic.com/automate-workflows/5-mins-tag-resources/).

## Read tags for an entity [#read-tags]

To construct these queries and see responses:

1.  Go to the NerdGraph GraphiQL explorer at [api.newrelic.com/graphiql](https://api.newrelic.com/graphiql).
2.  Use [`entitySearch()`](https://docs.newrelic.com/docs/apis/graphql-api/tutorials/use-new-relic-graphql-api-query-entities#search-entity) to find the entity and then fetch its tags.
3.  Use NerdGraph's tag API to read the existing tags and their values.

In this example, our entity is a browser app called `Cookie Checkout`:

```graphql
{
  actor {
    entitySearch(query: "name like 'Cookie Checkout'") {
      results {
        entities {
          tags {
            key
            values
          }
        }
      }
    }
  }
}
```

The actual values vary depending on your data. Use the [New Relic GraphiQL explorer](https://api.newrelic.com/graphiql) to experiment with queries.

## Add tags for an entity [#add-tags]

To add new tags for an entity:

1.  Go to the NerdGraph GraphiQL explorer at [api.newrelic.com/graphiql](https://api.newrelic.com/graphiql).
2.  Use [`entitySearch()`](https://docs.newrelic.com/docs/apis/graphql-api/tutorials/use-new-relic-graphql-api-query-entities#search-entity) to locate the GUID for the entity you want to tag.
3.  Use the `taggingAddTagsToEntity` mutation to add a tag with a value to the entity.
4.  For APM agents, a restart is required after adding a new tag.

In this example, we have a browser application called `Cookie Checkout` owned by a UI team. We want to add a `team` tag with a `ui` value to this instance. Once the tag is added, we can filter by the tag `team:ui` and find the `Cookie Checkout` app in the New Relic UI.

```graphql
mutation {
  taggingAddTagsToEntity(
    guid: "ENTITY_GUID"
    tags: { key: "team", values: ["ui"] }
  ) {
    errors {
      message
    }
  }
}
```

## Remove a tag from an entity [#delete-entity-tag]

To delete a tag and all of its associated values from an entity:

1.  Go to the NerdGraph GraphiQL explorer at [api.newrelic.com/graphiql](https://api.newrelic.com/graphiql).
2.  Use [`entitySearch()`](https://docs.newrelic.com/docs/apis/graphql-api/tutorials/use-new-relic-graphql-api-query-entities#search-entity) to locate the GUID for the entity with the tag you want to remove.
3.  Use the `taggingDeleteTagFromEntity` mutation.
4.  For APM agents, a restart is required after changing tags.

The following example mutation removes the `team` tag from an entity:

```graphql
mutation {
  taggingDeleteTagFromEntity(
    guid: "ENTITY_GUID", 
    tagKeys: ["team"]
  ) {
    errors {
      message
    }
  }
}
```

## Delete specific tag values for an entity [#delete-specific-tag]

Instead of deleting an entire tag and all of its values, you can delete a single tag value.

1.  Go to the NerdGraph GraphiQL explorer at [api.newrelic.com/graphiql](https://api.newrelic.com/graphiql).
2.  Use [`entitySearch()`](https://docs.newrelic.com/docs/apis/graphql-api/tutorials/use-new-relic-graphql-api-query-entities#search-entity) to locate the GUID for the entity with the tag you want to remove.
3.  Use the `taggingDeleteTagValuesFromEntity` mutation.

The following example mutation deletes the `ui` value from the `tag` key:

```graphql
mutation {
  taggingDeleteTagValuesFromEntity(
    guid: "ENTITY_GUID"
    tagValues: [{ key: "team", value: "ui" }]
  ) {
    errors {
      message
    }
  }
}
```

Because `tagValues` is an array, you can delete multiple specific values from a single entity in one mutation.

## Replace all tag values for an entity [#replace-tag-values]

To replace the entity’s entire set of tags with the provided tag set:

1.  Go to the NerdGraph GraphiQL explorer at [api.newrelic.com/graphiql](https://api.newrelic.com/graphiql).
2.  Use [`entitySearch()`](https://docs.newrelic.com/docs/apis/graphql-api/tutorials/use-new-relic-graphql-api-query-entities#search-entity) to locate the GUID for the entity with the tag you want to remove.
3.  Use the `taggingReplaceTagsOnEntity` mutation.

In this example, the `Cookie Checkout` browser application was transferred from the `ui` team to the `cookie-dev` team. You can replace the tag values for `team` with the following mutation:

```graphql
mutation {
  taggingReplaceTagsOnEntity(
    guid: "ENTITY_GUID"
    tags: { key: "team", values: ["cookie-dev"] }
  ) {
    errors {
      message
    }
  }
}
```