Grafana Cloud

Graphite HTTP API

The HTTP API is the same as that of Graphite, with the addition of ingestion, authentication, series lineage, meta tags and storage-aggregation/storage-schemas.conf endpoints.

First of all, there are two endpoints you will be talking to. They are provided on your Hosted Metrics instance details page.

They will look something like:

  • <ingest_endpoint> :
  • <query_endpoint> :

Furthermore, you will need to provision API keys to talk to the API. Each key will be of one of these types:

  • Viewer
  • MetricsPublisher
  • Editor
  • Admin

A “Viewer” key can only be used to execute queries, while a “MetricsPublisher” key can only be used to push metrics into the platform. “Editor” and “Admin” keys can be used for both pushing metrics and performing queries.

API keys can be provisioned on your organization page under “Security > API Keys”.


Authentication differs depending on whether your instance is provisioned on a dedicated or a shared cluster. How to tell the difference? On your instance details page, if your query and metrics endpoint look generic like this:

Then you are on a shared cluster. However if your URL’s look more like this:

Then you are on a dedicated cluster.

You have several ways to authenticate:

  • For dedicated clusters, any of these HTTP headers will work:
Authorization: Basic base64(api_key:<api key>)
Authorization: Bearer <api key>
Authorization: Bearer api_key:<api key>
  • For shared clusters, use any of these HTTP headers:
Authorization: Basic base64(<instance id>:<api key>)
Authorization: Bearer <instance id>:<api key>

Note that you can find the instance ID as the username in the “Using Grafana with Hosted Metrics” section of your instance details page

So essentially you can use basic auth with username “api_key” (for dedicated clusters) or your instance ID (for shared clusters) and password the api key that you provisoned

You can also use a bearer token in “username:password” format (if username not specified, “api_key” is assumed)

Common Request Parameters

Many of the API methods involve using Graphite patterns (queries), tag queries and the standard Graphite from/to syntax.

Graphite Patterns

Graphite patterns are queries that involve glob patterns (*, {}, [], ?).

Tag Expressions

Tags expressions are strings, and may have the following formats:

tag=spec    tag value exactly matches spec
tag!=spec   tag value does not exactly match spec
tag=~value  tag value matches the regular expression spec
tag!=~spec  tag value does not match the regular expression spec

Any tag spec that matches an empty value is considered to match series that don’t have that tag, and at least one tag spec must require a non-empty value. Regular expression conditions are treated as being anchored at the start of the value.

From/To (Until)

Graphite from/to


Adding New Data: Posting To /metrics

The main entry point for any publisher to publish data to, be it carbon-relay-ng, or any other script or application such as the hosted-metrics-sender-example

  • Method: POST
  • API key type: any (including Viewer)


  • Authorization: header is required (see authentication section above)
  • Content-Type: supports 3 values:
    • application/json: the simplest one, and the one used here
    • rt-metric-binary: same datastructure, but messagepack encoded. (see the MetricData Marshal/Encode methods)
    • rt-metric-binary-snappy: same as above, but snappy compressed.

Data Format

Each metricpoint message can have the following properties:

name     // Graphite style name (required)
interval // the resolution of the metric in seconds (required)
value    // float64 value (required)
time     // unix timestamp in seconds (required)
tags     // list of key=value pairs of tags (optional)


timestamp_now_rounded=$(($(date +%s) / 10 * 10))
timestamp_prev_rounded=$((timestamp_now_rounded - 10))

curl -X POST -H "Authorization: Bearer <key> -H "Content-Type: application/json" "<ingest_endpoint>" -d '[{
    "name": "test.metric",
    "interval": 10,
    "value": 12.345,
    "time": '$timestamp_prev_rounded'
    "name": "test.metric",
    "interval": 10,
    "value": 12.345,
    "time": '$timestamp_now_rounded'
    "name": "test.metric.tagged",
    "interval": 10,
    "value": 1,
    "tags": ["foo=bar", "baz=quux"],
    "time": '$timestamp_prev_rounded'
    "name": "test.metric.tagged",
    "interval": 10,
    "value": 2,
    "tags": ["foo=bar", "baz=quux"],
    "time": '$timestamp_now_rounded'

Tag Exploration

Count tag values With /tags/terms

Returns count of series for each tag value which matches tag queries for a given set of tag keys.

  • Method: GET or POST
  • API key type: any (including MetricsPublisher)
  • Authorization: Bearer <api-key> required
  • expr (required): a list of tag expressions
  • tags: a list of tag keys for which to count values series
curl -H "Authorization: Bearer <key>" "<query_endpoint>/tags/terms?expr=datacenter=dc1&expr=server=web01&tags=rack"

  "totalSeries": 5892,
  "terms": {
    "rack": {
      "a1": 2480,
      "a2": 465,
      "b1": 2480,
      "b2": 467

Render /render (return data for a given query)

Graphite-web-like api. It can return JSON, pickle or messagepack output

  • Method: GET or POST (recommended. as GET may result in too long URL’s)
  • API key type: any (viewer, publisher, editor)
  • Authorization: Bearer <api-key> required
  • maxDataPoints: int (default: 800)
  • target: mandatory. one or more metric names or patterns.
  • from: see timespec format (default: 24h ago) (exclusive)
  • to/until: see timespec format(default: now) (inclusive)
  • format: json, msgp, pickle, csv or msgpack (default: json) (note: msgp and msgpack are similar, but msgpack is for use with Graphite)
  • meta: Use ‘meta=true’ to enable performance and series lineage metadata in the response body. Only supported for json responses. See below for more information.

Data queried for must be stored under the given org or be public data (see multi-tenancy)


curl -H "Authorization: Bearer <key>" "<query_endpoint>/render?target=statsd.fakesite.counters.session_start.*.count&from=-3h&to=-2h"

Adjust storage-schemas.conf and storage-aggregation.conf

Grafana Cloud Graphite V5 allows for dynamic changing of both the graphite schemas and aggregation configuration. When interval data or rollups are poorly configured (e.g. defaults not matching the real data or their intended use) this can result in suboptimal visualizations. By correcting the configuration you can fix the problem. Unlike Graphite, changes are applied automatically retroactively without any loss of information. You can post as many changes as needed. If you do not update this configurations, the default Grafana Cloud settings will be applied instead.

Carbon-relay-NG version 1.2 or later will automatically push both of these files for you

Carbon-relay-ng is the recommended way of publishing these files, but you can manually use this endpoint when:

  1. you haven’t upgraded your relay yet.
  2. you want to experiment iteratively without having to repeatedly restart your relay.

There are two URL paths:

  • /graphite/config/storageSchema for posting storage-schemas.conf

  • /graphite/config/storageAggregation for posting storage-aggregation.conf

  • Method: POST

  • Authorization: Bearer <api-key> required

None. the body is the file contents


curl -H "Authorization: Bearer <key>" "<query_endpoint>/config/storageSchema" --data-binary '@<path-to-your-storage-schemas.conf>'
curl -H "Authorization: Bearer <key>" "<query_endpoint>/config/storageAggregation" --data-binary '@<path-to-your-storage-aggregation.conf>'