Grafana Tempo Search API
The Search API from Grafana Tempo — 5 operation(s) for search.
OpenAPI Specification
openapi: 3.1.0
info:
title: Grafana Tempo HTTP Echo Search API
description: Grafana Tempo HTTP API for querying traces, searching with TraceQL, and retrieving trace metadata. Tempo is an open-source, high-scale distributed tracing backend.
version: 2.0.0
contact:
name: Grafana Labs
url: https://grafana.com/oss/tempo/
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: http://localhost:3200
description: Default Tempo server
tags:
- name: Search
paths:
/api/search:
get:
operationId: searchTraces
summary: Search for traces
description: Searches for traces matching the given parameters. Supports tag-based search and TraceQL queries.
parameters:
- name: q
in: query
description: TraceQL query string
schema:
type: string
- name: tags
in: query
description: Tag-based search in logfmt format, e.g. "service.name=myservice error=true"
schema:
type: string
- name: minDuration
in: query
description: Minimum trace duration, e.g. "1.5s" or "500ms"
schema:
type: string
- name: maxDuration
in: query
description: Maximum trace duration
schema:
type: string
- name: limit
in: query
description: Maximum number of traces to return
schema:
type: integer
default: 20
- name: start
in: query
description: Start of time range in Unix epoch seconds
schema:
type: integer
- name: end
in: query
description: End of time range in Unix epoch seconds
schema:
type: integer
- name: spss
in: query
description: Spans per span set, limits spans returned per set
schema:
type: integer
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request
'500':
description: Internal server error
tags:
- Search
/api/search/tags:
get:
operationId: getSearchTags
summary: Get search tag names
description: Returns a list of tag names that can be used for search.
parameters:
- name: scope
in: query
description: Scope of tags to return (resource, span, or intrinsic)
schema:
type: string
enum:
- resource
- span
- intrinsic
- name: start
in: query
description: Start of time range in Unix epoch seconds
schema:
type: integer
- name: end
in: query
description: End of time range in Unix epoch seconds
schema:
type: integer
responses:
'200':
description: A list of tag names
content:
application/json:
schema:
$ref: '#/components/schemas/TagNamesResponse'
tags:
- Search
/api/search/tag/{tagName}/values:
get:
operationId: getSearchTagValues
summary: Get values for a tag
description: Returns a list of values for a given tag name.
parameters:
- name: tagName
in: path
required: true
description: The tag name to lookup values for
schema:
type: string
- name: q
in: query
description: TraceQL query to filter values by
schema:
type: string
- name: start
in: query
description: Start of time range in Unix epoch seconds
schema:
type: integer
- name: end
in: query
description: End of time range in Unix epoch seconds
schema:
type: integer
responses:
'200':
description: A list of tag values
content:
application/json:
schema:
$ref: '#/components/schemas/TagValuesResponse'
tags:
- Search
/api/v2/search/tags:
get:
operationId: getSearchTagsV2
summary: Get search tag names (v2)
description: Returns tag names with their scopes. V2 endpoint provides scope information alongside tag names.
parameters:
- name: scope
in: query
description: Scope of tags to return
schema:
type: string
enum:
- resource
- span
- intrinsic
- name: start
in: query
schema:
type: integer
- name: end
in: query
schema:
type: integer
responses:
'200':
description: Scoped tag names
content:
application/json:
schema:
$ref: '#/components/schemas/TagNamesV2Response'
tags:
- Search
/api/v2/search/tag/{tagName}/values:
get:
operationId: getSearchTagValuesV2
summary: Get values for a tag (v2)
description: Returns tag values with their types.
parameters:
- name: tagName
in: path
required: true
schema:
type: string
- name: q
in: query
description: TraceQL query to filter values
schema:
type: string
- name: start
in: query
schema:
type: integer
- name: end
in: query
schema:
type: integer
responses:
'200':
description: Tag values with types
content:
application/json:
schema:
$ref: '#/components/schemas/TagValuesV2Response'
tags:
- Search
components:
schemas:
TagNamesResponse:
type: object
properties:
tagNames:
type: array
items:
type: string
TagNamesV2Response:
type: object
properties:
scopes:
type: array
items:
type: object
properties:
name:
type: string
tags:
type: array
items:
type: string
KeyValue:
type: object
properties:
key:
type: string
value:
type: object
properties:
stringValue:
type: string
intValue:
type: string
doubleValue:
type: number
boolValue:
type: boolean
TraceSearchMetadata:
type: object
properties:
traceID:
type: string
rootServiceName:
type: string
rootTraceName:
type: string
startTimeUnixNano:
type: string
durationMs:
type: integer
spanSets:
type: array
items:
type: object
properties:
spans:
type: array
items:
type: object
properties:
spanID:
type: string
startTimeUnixNano:
type: string
durationNanos:
type: string
attributes:
type: array
items:
$ref: '#/components/schemas/KeyValue'
matched:
type: integer
SearchResponse:
type: object
properties:
traces:
type: array
items:
$ref: '#/components/schemas/TraceSearchMetadata'
metrics:
type: object
properties:
inspectedTraces:
type: integer
inspectedBytes:
type: integer
TagValuesV2Response:
type: object
properties:
tagValues:
type: array
items:
type: object
properties:
type:
type: string
value:
type: string
TagValuesResponse:
type: object
properties:
tagValues:
type: array
items:
type: string