Traces API Reference

Kloudfuse serves a Tempo-compatible trace search API. Unlike the logs and metrics APIs, it is exposed only through the embedded Grafana’s datasource proxy — requests go to the KfuseTraceDatasource proxy path rather than a public endpoint. Queries use TraceQL.

Replace <your-instance> with your Kloudfuse hostname, <sa-token> with a valid Service Account token, and <ds-uid> with the trace datasource UID.

curl -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search?q=<traceql>"
bash

For Service Account token setup, see Authentication. Failed requests return the standardized status codes and JSON error payload described in API Response Codes.

Find the datasource UID

List the Grafana datasources and take the UID of the tempo-type entry:

curl -s -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources" | \
  python3 -c "import json,sys; print([d['uid'] for d in json.load(sys.stdin) if d['type']=='tempo'])"
bash

GET …​/api/search runs a TraceQL query and returns the matching traces with their matched span sets.

Parameters:

Parameter Type Required Description

q

string

Yes

The TraceQL query.

start

Unix seconds

Yes

Start of the time range.

end

Unix seconds

Yes

End of the time range.

limit

int

No

Maximum traces to return.

Response fields (per trace):

Field Description

traceID

Hex trace identifier; use it with Retrieve a trace by ID.

rootServiceName

Service of the trace’s root span.

rootTraceName

Operation name of the root span.

startTimeUnixNano

Trace start time, nanoseconds.

durationMs

Whole-trace duration in milliseconds.

spanSets

The spans that matched the query, with their attributes and a matched count.
Server spans of a service
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search" \
     --data-urlencode 'q={.service_name = "demo-python-service" && kind = server}' \
     --data-urlencode "start=$(date -u -v-15M +%s)" \
     --data-urlencode "end=$(date -u +%s)" \
     --data-urlencode "limit=1"
bash
Response (truncated)
{
  "traces": [
    {
      "traceID": "ead84305013f7d5cead227e0928569d3",
      "rootServiceName": "demo-python-service",
      "rootTraceName": "database",
      "startTimeUnixNano": "1783216821887904312",
      "durationMs": 50,
      "spanSets": [
        {
          "spans": [
            {
              "spanID": "eaef31bb76b7ae71",
              "startTimeUnixNano": "1783216821887904312",
              "durationNanos": "50212051",
              "attributes": [
                { "key": "service_name", "value": { "stringValue": "demo-python-service" } }
              ]
            }
          ],
          "matched": 1
        }
      ]
    }
  ],
  "metrics": {}
}
json

Retrieve a trace by ID

GET …​/api/traces/{traceID} returns the complete trace — every span with full attributes, in OTLP resource-span form. Use the traceID from a search result.

Parameters:

Parameter Type Required Description

{traceID}

path

Yes

Hex trace ID from a search result.
Fetch one trace
curl -s -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/traces/ead84305013f7d5cead227e0928569d3"
bash
Response (truncated)
{
  "trace": {
    "resourceSpans": [
      {
        "resource": {
          "attributes": [
            { "key": "service.name", "value": { "stringValue": "demo-python-service" } }
          ]
        },
        "scopeSpans": [
          {
            "scope": { "name": "demo-python-service" },
            "spans": [
              {
                "traceId": "6thDBQE/fVzq0ifgkoVp0w==",
                "spanId": "p5Tj0OVvhOo=",
                "name": "user",
                "startTimeUnixNano": "1783216821887961015",
                "endTimeUnixNano": "1783216821938079355"
              }
            ]
          }
        ]
      }
    ]
  }
}
json
In this endpoint’s OTLP-format response, traceId and spanId are base64-encoded bytes, not the hex strings used elsewhere.

List tag names

GET …​/api/search/tags lists the span and resource tags available for TraceQL conditions.

List tags
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search/tags" \
     --data-urlencode "start=$(date -u -v-15M +%s)" \
     --data-urlencode "end=$(date -u +%s)"
bash
Response (truncated)
{
  "tagNames": ["span_name", "telemetry_sdk_language", "span_status_code",
               "service_name", "service_namespace", "span_type", "error", "..."]
}
json

List tag values

GET …​/api/search/tag/{tagName}/values lists the values of one tag within the time range — the discovery step before writing a filter on that tag.

Parameters:

Parameter Type Required Description

{tagName}

path

Yes

The tag to enumerate.

start, end

Unix seconds

Yes

Time range to inspect.

q

string

No

A TraceQL query to restrict the values (v2 endpoint: /api/v2/search/tag/{tagName}/values).
Values of service_name
curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search/tag/service_name/values" \
     --data-urlencode "start=$(date -u -v-15M +%s)" \
     --data-urlencode "end=$(date -u +%s)"
bash
Response
{
  "tagValues": ["demo-go-service", "demo-java-service", "demo-python-service"]
}
json

Limitations

  • TraceQL metrics endpoints (/api/metrics/…​) are not available; use Trace Analytics for trace-derived metrics.

  • Live tail (/api/v1/tail-style streaming) is not supported.

  • For TraceQL language features not supported on Kloudfuse, see the TraceQL overview.