# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostedgraphite.com/api-guides/tag-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.