---
title: "GET /traces"
method: GET
path: "/traces"
---

# GET /traces

`GET /traces`

Invoking this request retrieves traces matching the below filters.

Results should be filtered against endTs, subject to limit and
lookback. For example, if endTs is 10:20 today, limit is 10, and
lookback is 7 days, traces returned should be those nearest to 10:20
today, not 10:20 a week ago.

Time units of endTs and lookback are milliseconds as opposed to
microseconds, the grain of Span.timestamp. Milliseconds is a more
familiar and supported granularity for query, index and windowing
functions

## Query parameters

- `serviceName` string
- `spanName` string
- `annotationQuery` string
- `minDuration` integer
- `maxDuration` integer
- `endTs` integer
- `lookback` integer
- `limit` integer

## Response `200`

OK

- Trace[]
  - Span[] — List of spans who have the same trace id. Spans in the trace, and annotations in a span are sorted ascending by timestamp. ie first event should be first in the spans list.
    - `traceId` string, required — Randomly generated, unique identifier for a trace, set on all spans within it. Encoded as 16 or 32 lowercase hex characters in big endian byte order, corresponding to 64 or 128 bits, For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3
    - `name` string, required — The logical operation this span represents in lowercase (e.g. rpc method). Set to empty string if unknown. As these are lookup labels, take care to ensure names are low cardinality. For example, do not embed variables into the name.
    - `parentId` string — The parent span ID or absent if this the root span in a trace.
    - `id` string, required — Unique 64bit identifier for this operation within the trace. Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3
    - `timestamp` integer — Epoch microseconds of the start of this span, possibly absent if incomplete. For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC This value should be set directly by instrumentation, using the most precise value possible. For example, gettimeofday or multiplying epoch millis by 1000. There are three known edge-cases where this could be reported absent. * A span was allocated but never started (ex not yet received a timestamp) * The span's start event was lost * Data about a completed span (ex tags) were sent after the fact
    - `duration` integer — Duration in **microseconds** of the critical path, if known. Durations of less than one are rounded up. Duration of children can be longer than their parents due to asynchronous operations. For example 150 milliseconds is 150000 microseconds.
    - `debug` boolean — True is a request to store this span even if it overrides sampling policy. This is true when the `X-B3-Flags` header has a value of 1.
    - `annotations` Annotation[] — Associates events that explain latency with the time they happened.
      - `timestamp` integer, required — Epoch **microseconds** of this event. For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC This value should be set directly by instrumentation, using the most precise value possible. For example, gettimeofday or multiplying epoch millis by 1000.
      - `value` string, required — Usually a short tag indicating an event, like "sr" While possible to add larger data, such as garbage collection details, low cardinality event names both keep the size of spans down and also are easy to search against.
      - `endpoint` Endpoint — The network context of a node in the service graph
        - `serviceName` string, required — Lower-case label of this node in the service graph, such as "favstar". Set to empty string if unknown. This is a primary label for trace lookup and aggregation, so it should be intuitive and consistent. Many use a name from service discovery.
        - `ipv4` string, ipv4 — The text representation of the primary IPv4 address associated with this connection. Ex. 192.168.99.100 Absent if unknown.
        - `ipv6` string, ipv6 — The text representation of the primary IPv6 address associated with a connection. Ex. 2001:db8::c001 Absent if unknown. Prefer using the ipv4 field for mapped addresses.
        - `port` integer — Depending on context, this could be a listen port or the client-side of a socket. Absent if unknown. Please don't set to zero.
    - `binaryAnnotations` BinaryAnnotation[] — Binary Annotations are tags that give your span context for search, viewing and analysis.
      - `key` string, required
      - `value` string, required
      - `endpoint` Endpoint — The network context of a node in the service graph
        - `serviceName` string, required — Lower-case label of this node in the service graph, such as "favstar". Set to empty string if unknown. This is a primary label for trace lookup and aggregation, so it should be intuitive and consistent. Many use a name from service discovery.
        - `ipv4` string, ipv4 — The text representation of the primary IPv4 address associated with this connection. Ex. 192.168.99.100 Absent if unknown.
        - `ipv6` string, ipv6 — The text representation of the primary IPv6 address associated with a connection. Ex. 2001:db8::c001 Absent if unknown. Prefer using the ipv4 field for mapped addresses.
        - `port` integer — Depending on context, this could be a listen port or the client-side of a socket. Absent if unknown. Please don't set to zero.

---

[API](https://skmtc.net/zipkin/apis/zipkin-api.md) · [All operations](https://skmtc.net/zipkin/apis/zipkin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zipkin/zipkin-api/revisions/696558132e8c/schema)