# Aggregation Rules API

Contents

* [Aggregation Rules API](https://docs.hostedgraphite.com/api-guides/aggregation-rules-api)
  * [Creating Aggregation Rules](#creating-aggregation-rules)
  * [Listing Aggregations](#listing-aggregations)
  * [List Aggregation Rules by ID](#list-aggregation-ules-by-id)
  * [Deleting Aggregates](#deleting-aggregates)
  * [Editing Your Aggregations](#editing-your-aggregations)

Aggregation rules consolidate the averaged values of many metrics into one, allowing for speedy graph rendering and visualization. Managing aggregation rules can be done easily with Hosted Graphite. Learn more about what our aggregation rules do, and how to use our Aggregation Feature [*here*](https://docs.hostedgraphite.com/additional-features/aggregation-rules).

### [Creating Aggregation Rules](#creating-aggregation-rules)

<mark style="color:green;">`POST`</mark> `/v1/aggregates/`

#### Path Parameters

| Name                                      | Type   | Description                                                                                                                       |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| pattern<mark style="color:red;">\*</mark> | String | Regex or node pattern to match ingested metrics to.                                                                               |
| output<mark style="color:red;">\*</mark>  | String | Metric output, when a metric is matched with the pattern, those metrics will be mapped to this output and appear in your account. |

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

(The aggregation rule was created successfully. Returns created aggregation’s ID)
{% endtab %}

{% tab title="400" %}
Bad Request Creation failed. Pattern or output is an invalid input (or not provided). Or the aggregation rule creation failed because the pattern is too computationally expensive to match against your metric names.
{% endtab %}

{% tab title="403" %}
Forbidden Creation failed, you have reached the limit for your account
{% endtab %}

{% tab title="409" %}
Conflict Creation failed, aggregation with this pattern & output already exists.
{% endtab %}

{% tab title="500" %}
Internal Server Error Creation failed due to a server error - this shouldn’t happen.
{% endtab %}
{% endtabs %}

**Curl Example**:

```bash
curl -H "Content-Type: application/json" -X POST -d \
'{"pattern": "servers.*.requests.<response_code>", "output": "servers.all.requests.<response_code>"}' \
"https://YOUR-API-KEY@api.hostedgraphite.com/v1/aggregates/"
```

Creates an aggregation with the pattern: `servers.*.requests.<response_code>` and the `output servers.all.requests.<response_code>`.&#x20;

For example, metrics that look like `servers.server-0001.requests.404` and `servers.server-0002.requests.404` would appear in your account as `aggregates.servers.all.requests.404`.

***

### [Listing Aggregations](#listing-aggregations)

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

{% tabs %}
{% tab title="200" %}
OK List of your aggregation rules.
{% endtab %}
{% endtabs %}

## [List Aggregation Rules by ID](#list-aggregation-rules-by-id)

<mark style="color:blue;">`GET`</mark> `/v1/aggregates/<aggregation_id>/`

Lists your aggregations or individual aggregation if the optional ID is passed.

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

Aggregation with passed ID if it exists, empty list otherwise.
{% endtab %}
{% endtabs %}

**Curl Example**:

```bash
curl "https://YOUR-API-KEY@api.hostedgraphite.com/v1/aggregates/<aggregation_id>/"
```

***

### [Deleting Aggregates](#deleting-aggregates)

<mark style="color:red;">`DELETE`</mark> `/v1/aggregates/<aggregate_id>/`

Delete aggregation rule with passed ID

{% tabs %}
{% tab title="200" %}
OK Aggregation was successfully deleted.
{% endtab %}

{% tab title="400" %}
Bad Request No aggregation ID passed.
{% endtab %}

{% tab title="412" %}
Precondition Failed Aggregation with passed ID does not exist.
{% endtab %}

{% tab title="500" %}
Internal Server Error Delete failed, please try again.
{% endtab %}
{% endtabs %}

**Curl Example**:

```bash
curl -X DELETE "https://YOUR-API-KEY@api.hostedgraphite.com/v1/aggregates/<aggregate_id>/"
```

***

### [Editing Your Aggregations](#editing-your-aggregations)

To edit an aggregation rule, you can do this through the Hosted Graphite UI. Additionally, aggregation rules have no state, so it is safe to delete and re-create them. Learn more about our [*Aggregate Rules Feature*](https://docs.hostedgraphite.com/additional-features/aggregation-rules).

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FhZoTFKHQwGUcbdIYxKZL%2Faggregate-rules-ui.png?alt=media&#x26;token=017acbda-ac33-47e3-a18e-e8c80a1164aa" alt=""><figcaption><p>Aggregate Rules UI</p></figcaption></figure>