---
title: "Metrics summary API (deprecated) | Grafana Cloud documentation"
description: "Learn how to use the metrics summary API in Grafana Cloud Traces"
---
# Metrics summary API (deprecated)
> Warning
>
> Metrics summary API and the **Aggregate by** feature are deprecated in Grafana Cloud and Grafana 11.3 and later. It will be removed in a future release.
This document explains how to use the metrics summary API in Grafana Cloud Traces. This API returns RED metrics (span count, erroring span count, and latency information) for `kind=server` spans sent to Grafana Cloud Traces in the last hour, grouped by a user-specified attribute.
## Activate metrics summary
The Metrics summary API is an [experimental feature](/docs/release-life-cycle/) that is disabled by default. To enable it, contact Grafana Support.
## Request
To make a request to this API, use the following URL:
 Copy
```none
https://$URL/api/metrics/summary
```
Example:
 Copy
```none
GET https://tempo-dedicated-02-prod-us-central-0.grafana.net/tempo/api/metrics/summary
```
To get the value of `$URL`:
1. Go to grafana.com.
2. Select **Details** for your stack.
3. Select **Details** for your Tempo tracing service.
4. Use the value under **URL** in the **Grafana Data Source settings**.
### Authentication
The API uses HTTP basic authentication.
For your username, use the **User** value in the Grafana Data Source settings.
For your password, use a Cloud Access Policy token. Create an access policy with the `traces:read` scope and then create a token for that access policy. Use the token as your password.
Example:
 Copy
```none
GET -u "$USER:$PASSWORD" "$URL/api/metrics/summary"
```
Replace `$USER`, `$PASSWORD`, and `$URL` with the values for your username, password, and URL.
### Query parameters
All query parameters must be URL-encoded to preserve non-URL-safe characters in the query such as `&`.
Expand table
| Name | Examples | Definition | Required? |
|-----------|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-----------|
| `q` | `{ resource.service.name = "foo" && span.http.status_code != 200 }` | The TraceQL query with full syntax. All spans matching this query are included in the calculations. Any valid TraceQL query is supported. | Yes |
| `groupBy` | `name`
`.foo`
`resource.namespace`
`span.http.url,span.http.status_code` | The TraceQL value(s) to group by. Any valid intrinsic or attribute with scope. To group by multiple values use a comma-delimited list. | Yes |
| `start` | 1672549200 | Start of time range in unix seconds. If not specified, then all recent data is queried. | No |
| `end` | 1672549200 | End of the time range in unix seconds. If not specified, then all recent data is queried. | No |
Example:
Bash  Copy
```bash
curl -u "$USER:$PASSWORD" "$URL/api/metrics/summary" --data-urlencode 'q={resource.service.name="checkout-service"}' --data-urlencode 'groupBy=name'
```
## Response
The Tempo response is a `SpanMetricsSummary` object defined in [tempo.proto](https://github.com/grafana/tempo/blob/main/pkg/tempopb/tempo.proto#L234), relevant section pasted below:
 Copy
```none
message SpanMetricsSummaryResponse {
repeated SpanMetricsSummary summaries = 1;
}
message SpanMetricsSummary {
uint64 spanCount = 1;
uint64 errorSpanCount = 2;
TraceQLStatic static = 3;
uint64 p99 = 4;
uint64 p95 = 5;
uint64 p90 = 6;
uint64 p50 = 7;
}
message TraceQLStatic {
int32 type = 1;
int64 n = 2;
double f = 3;
string s = 4;
bool b = 5;
uint64 d = 6;
int32 status = 7;
int32 kind = 8;
}
```
The response is returned as JSON following [standard protobuf->JSON mapping rules](https://protobuf.dev/programming-guides/proto3/#json).
> Note
>
> The `uint64` fields cannot be fully expressed by JSON numeric values so the fields are serialized as strings.
Example:
JavaScript  Copy
```javascript
{
"summaries": [
{
"spanCount": "20",
"series" : [
{
"key": ".attr1",
"value": {
"type": 5,
"s": "foo"
},
},
...
],
"p99": "68719476736",
"p95": "1073741824",
"p90": "1017990479",
"p50": "664499239"
},
```
Expand table
| Field | Notes |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `summaries` | The list of metrics per group. |
| `.spanCount` | Number of spans in this group. |
| `.errorSpanCount` | Number of spans with `status`=`error`. (This field will not be present if the value is `0`.) |
| `.series` | The unique values for this group. A key/value pair will be returned for each entry in `groupBy`. |
| `.key` | Key name. |
| `.value` | Value with TraceQL underlying type. |
| `.type` | Data type enum defined [here](https://github.com/grafana/tempo/blob/main/pkg/traceql/enum_statics.go#L8) (This field will not be present if the value is `0`.)
0 = nil
3 = integer
4 = float
5 = string
6 = bool
7 = duration
8 = span status
9 = span kind |
| `.n` | Populated if this is an integer value. |
| `.s` | Populated if this is a string value. |
| `.f` | Populated if this is a float value. |
| `.b` | Populated if this is a boolean value. |
| `.d` | Populated if this is a duration value. |
| `.status` | Populated if this is a span status value. |
| `.kind` | Populated if this is a span kind value. |
| `.p99` | The p99 latency of this group in nanoseconds. |
| `.p95` | The p95 latency of this group in nanoseconds. |
| `.p90` | The p90 latency of this group in nanoseconds. |
| `.p50` | The p50 latency of this group in nanoseconds. |