# Metrics API

Contents

* [Metrics API](/api-guides/metrics-api.md)
  * [Searching Metrics](#searching-metrics)
  * [Busy Metrics](#busy-metrics)
  * [Invalid Metrics](#invalid-metrics)
  * [Deleting Metrics](#deleting-metrics)

### [Searching Metrics](#searching-metrics)

## Locate Metrics

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

#### Path Parameters

| Name                                      | Type   | Description                                                                                                          |
| ----------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| pattern<mark style="color:red;">\*</mark> |        | \[required] metric pattern to search for                                                                             |
| only\_updated\_after                      | String | <p>To limit search results for metrics that only received data points in the last n hours </p><p></p>                |
| only\_updated\_before                     | String | To limit search results for metrics that have not received data points in the last n month                           |
| with\_times                               | String | To return the first (“created\_at”) and last (“last\_updated”) seen timestamp for that metric                        |
| page                                      | String | Return the nth page of results, for searches that return more than the maximum page size (default maximum size: 100) |

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

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

```json
{
  "results": [
    "foo.bar.1",
    "foo.bar.2"
  ],
  "metrics_matched": 2,
  "total_metrics": 12345,
  "next_page": 2
}
```

{% endtab %}

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

**Curl examples:**

```
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/metric/search?pattern=foo.bar.*"
```

Search for metrics that match the pattern `foo.bar.*`

```
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/metric/search?pattern=*&only_updated_before=30d"
```

Search for all (\*) metrics that have not received data for 30d

**Response format for: `&with_times=true`**:

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

{
  "results": ["foo.bar.1", "foo.bar.2"],
  "metrics_matched": 2,
  "total_metrics": 12345,
  "times": {
    "foo.bar.1": {
      "created_at": 1234567890,
      "last_updated": 1234567890
    },
    "foo.bar.2": {
      "created_at": 1234567890,
      "last_updated": 1234567890
    }
  }
}
```

***

### [Busy Metrics](#busy-metrics)

## Locate Busy Metrics

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

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

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

```json
{
  "metric": "busy-metric.1",
  "pct_ratelimited": 60
}
```

{% endtab %}

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

**Curl Example:**

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

***

### [Invalid Metrics](#invalid-metrics)

## Locate Invalid Metrics

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

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

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

```json
{
  "metric": "busy-metric.1",
  "pct_ratelimited": 60
}
```

{% endtab %}

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

**Curl example:**

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

***

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

## Delete Metrics

<mark style="color:green;">`DELETE`</mark> `/api/v1/metric/delete`

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

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

**Curl example:**

```
curl -X DELETE "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/metric/delete" -d '{"pattern":"test.*"}'
```

Delete all metrics that match the pattern `test.*`.

Legacy **POST** route:

<mark style="color:green;">`POST`</mark> `/api/v1/metric/delete`

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

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

**Curl example:**

```
curl --http1.1  -d "pattern=foo.bar.*" "https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/metric/delete/"
```

Delete all metrics that match the pattern `foo.bar.*`.


---

# 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/metrics-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.