Add, list, delete labels (deprecated)

DEPRECATED

The use of the REST API for labels/tags is deprecated. For how to add tags, see Tags.

Create labels

The use of the REST API for labels/tags is deprecated. For how to add tags, see Tags.

Creating or applying a label with the REST API requires:

Use a command similar to the following example to apply a label to an application that exists in your account. Substitute your user key and the application id in the example.

You can use this command to apply the same label to applications and hosts simultaneously. You can also omit the "applications": section if not needed.

curl -X PUT 'https://api.newrelic.com/v2/labels.json' \
     -H "Api-Key:NEW_RELIC_USER_KEY" -i \
     -H 'Content-Type: application/json' \
     -d \
'{
  "label": {
    "category": "Production",
    "name": "Web01",
    "links": {
      "applications": [
        123456,7898765     <---<< application ids
      ],
    }
  }
}' 

Create label: View the output

The output for creating or applying a label will appear similar to the following example for a single application. The label output includes:

  • The full key name for the label (for example, Production:Main), as well as the component and name for the key
  • The application health_status (red, orange, green, gray) and the application IDs for the label in each category; for example, the health status for app ID 546917 is green (the app is fine)
  • Apps that have this label; for example, the label Production:Main has been applied to one application (546917)
{
  "label": {
    "key": "Production:Main",
    "category": "Production",
    "name": "Main",
    "application_health_status": {
      "green": [
        546917        <---application id
      ],
      "orange": [],
      "red": [],
      "gray": []
    },
    "links": {
      "applications": [
        546917        <--- application id
      ],
    }
  },
...
}

Create label return status

There are two possible return statuses when creating labels:

Return status Definition
201 Create A label was successfully created.
304 Not Modified There was an attempt to re-create an existing label, but no change was needed or made.

List existing labels

The use of the REST API for labels/tags is deprecated. For how to use tags, see Tags.

To list the labels that exist in your account, use this command:

curl 'https://api.newrelic.com/v2/labels.json' \
     -H "Api-Key:NEW_RELIC_USER_KEY" -i 

View the output

The output for the label includes:

  • The full key name for the label (for example, Staging:Test1), as well as the component and name for the key
  • The application health_status (red, orange, green, gray) and application IDs for the label in each category
  • Apps that have this label; for example, the label Staging:Test1 has been applied to one application (4937390) and two hosts (3801143 and 5879721)

The output for a label listing will appear similar to this:

{
  "labels": [
    {
      "key": "Production:Main",
      "category": "Production",
      "name": "Main",
      "application_health_status": {
        "green": [],
        "orange": [],
        "red": [],
        "gray": []
      },
      "links": {
        "applications": [],
      }
    },
    {
      "key": "Staging:Test1",
      "category": "Staging",
      "name": "Test1",
      "application_health_status": {
        "green": [],
        "orange": [],
        "red": [
          4937390
        ],
        "gray": []
      },
      "links": {
        "applications": [
          4937390
        ],
      }
    },
...
}

Delete labels

The use of the REST API for labels/tags is deprecated. For how to use tags, see Tags.

This API call will remove all instances of the label from both applications and hosts. If you want to remove a label from a specific application or host, you must use the New Relic UI.

Use a command similar to the following example to delete a label from your account.

curl -X DELETE 'https://api.newrelic.com/v2/labels/Production:Main.json' \
     -H "Api-Key:NEW_RELIC_USER_KEY" -i

You can also use the New Relic REST API Explorer (v2) to delete labels.

Deleting: view the output

The output for deleting a label will appear similar to the following example for a single application. This example will delete the label Production:Main from all locations where it was applied for the account's REST API key.

The output for deleting labels includes:

  • The full key name for the label (for example, Production:Main), as well as the component and name for the key
  • The application health_status (red, orange, green, gray) and the IDs for the label in each category; for example, the health status for app ID 546917 is green (the app is fine)
  • Apps that have this label; for example, the label Production:Main has been removed from one application (546917)
{
  "label": {
    "key": "Production:Main",
    "category": "Production",
    "name": "Main",
    "application_health_status": {
      "green": [
        546917
      ],
      "orange": [],
      "red": [],
      "gray": []
    },
    "links": {
      "applications": [
        546917
      ],
    }
  },
  ....
}

Delete return status

There are two possible return statuses when deleting labels:

Return status Definition
200 OK An attempt to delete a label was successful.
404 Not Modified An attempt was made to delete a non-existent label.

For more help

If you need more help, check out these support and learning resources: