> For the complete documentation index, see [llms.txt](https://docs.hostedgraphite.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostedgraphite.com/api-guides/tag-api.md).

# Tag API

Contents

* [Tag API](/api-guides/tag-api.md)
  * [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&amp;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&amp;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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.