# Tag API

Contents

* [Tag API](https://docs.hostedgraphite.com/api-guides/tag-api)
  * [Listing All Tags](#listing-all-tags)
  * [Search Tagged Metrics](#search-tagged-metrics)
  * [Locate Tagged Metrics and Values](#locate-tagged-metrics-and-values)
  * [Deleting Tagged Metrics](#deleting-tagged-metrics)
  * [Monitoring your Tagged Metrics usage](#monitoring-your-tagged-metrics-usage)

### [Listing All Tags](#listing-all-tags)

<mark style="color:blue;">`GET`</mark> `GET /api/v1/tags`

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: application/json
```

```json
[
  "cluster",
  "host",
  "process",
  "service",
  "name"
]
```

{% endtab %}

{% tab title="400" %}
Bad Request
{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/tags"
```

***

### [Search Tagged Metrics](#search-tagged-metrics)

<mark style="color:blue;">`GET`</mark> `GET /api/v1/tags/<tagname>`

#### Path Parameters

| Name   | Type   | Description                                                                                                         |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------- |
| expr   | String | To search for the tagged series that match the expression, users should include both tagname and value in the query |
| filter | String | Tag value to search for                                                                                             |
| limit  | String | To limit the number of search results to the given number                                                           |

{% tabs %}
{% tab title="200 " %}
OK
{% endtab %}

{% tab title="400 " %}
Bad Request
{% endtab %}

{% tab title="501" %}
Not Implemented
{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/tags/host?filter=prod-00*&limit=3"
```

Search for tag name `host` that matches the value `prod`, and only show 3 matching results.

### [Locate Tagged Metrics and Values](#locate-tagged-metrics-and-values)

<mark style="color:blue;">`GET`</mark> `/api/v1/tags/findSeries?`

#### Path Parameters

| Name   | Type   | Description                                                                                                                                                                                                              |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| expr   | String | <p>Format: <code>expr=tagname=tagvalue or expr=tagname1=tagvalue1\&tagname2=tagvalue2</code><br>To search for the tagged series that match the expression, users should include both tagname and value in the query.</p> |
| filter | String | <p>Format: <code>filter=prod-00\*</code><br>Tag value to search for.</p>                                                                                                                                                 |
| limit  | String | <p>Format: <code>limit=3</code><br>To limit the number of search results to the given number.</p>                                                                                                                        |

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: application/json 
```

```json
[
  "0.queue_backlog;cluster=prod;host=prod-egg-0021;process=grind;service=data_process",
  "2.queue_backlog;cluster=prod;host=prod-egg-0021;process=grind;service=data_process",
  "0.items;cluster=prod;host=prod-egg-001;process=dump;service=data_process"
]
```

{% endtab %}

{% tab title="400 " %}
Bad Request
{% endtab %}

{% tab title="500 " %}
Internal Server Error
{% endtab %}
{% endtabs %}

**Curl examples:**

```bash
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/tags/findSeries?expr=cluster=prod&host=egg-0001"
```

Search for tagged metric/series that match the expression `cluster=prod&host=egg-0001`

**Response format with ‘`?filter=machine-000*&limit=3`’**:

```json
HTTP/1.1 200
Content-Type: application/json

{"tag": "host",
 "values": [{"count": 59, "value": "machine-0001"},
            {"count": 57, "value": "machine-0002"},
            {"count": 59, "value": "machine-0003"}]
}
```

***

### [Deleting Tagged Metrics](#deleting-tagged-metrics)

<mark style="color:green;">`POST`</mark> `/api/v1/tags/delSeries`

{% tabs %}
{% tab title="200 " %}
OK
{% endtab %}

{% tab title="400 " %}
Bad Request
{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X POST "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/tags/delSeries" --data-urlencode "path=foo.bar;tag1=val1;tag2=val2"
```

Delete all series that match the path *foo.bar* and *tag1=val1* and *tag2=val2*.

***

### [Monitoring your Tagged Metrics usage](#monitoring-your-tagged-metrics-usage)

If you have sent tagged metrics then the number of tagged metrics you have sent will be displayed when you hover over the metric count on your [Homepage](https://www.hostedgraphite.com/app/):

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FafEB1hptwanz6Pvs26Fz%2Ftotal-tags-onhover.png?alt=media&#x26;token=83701843-7f74-44fe-9503-7d45e1601b7e" alt=""><figcaption><p>Total Tags in Account</p></figcaption></figure>

You can also locate, search, and delete your tagged metrics from within our Tag Search UI:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FsVfdubr3WTPhYvkvVfeK%2Ftag-search-ui.png?alt=media&#x26;token=3e8253d9-dfe2-4cfa-ac37-604237dfcf8a" alt=""><figcaption><p>Tag Search UI</p></figcaption></figure>

<figure><img src="https://www.hostedgraphite.com/docs/_images/tagged_metric_count_homepage.png" alt=""><figcaption></figcaption></figure>