---
title: "Returns a list of MeshTrace in the mesh."
method: GET
path: "/v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshtraces"
tags: ["MeshTrace"]
---

# Returns a list of MeshTrace in the mesh.

`GET /v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshtraces`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshtraces`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `mesh` string, required

## Query parameters

- `offset` integer
- `size` integer
- `filter` object
  - `key` string
  - `value` string

## Response `200`

List

- object
  - `items` MeshTraceItem[]
    - `type` 'MeshTrace', required: the type of the resource
    - `mesh` string: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources.
    - `kri` string: A unique identifier for this resource instance used by internal tooling and integrations. Typically derived from resource attributes and may be used for cross-references or indexing
    - `name` string, required: Name of the Kuma resource
    - `labels` object: The labels to help identity resources
    - `spec` object, required: Spec is the specification of the Kuma MeshTrace resource.
      - `default` object: MeshTrace configuration.
        - `backends` object[]: A one element array of backend definition. Envoy allows configuring only 1 backend, so the natural way of representing that would be just one object. Unfortunately due to the reasons explained in MADR 009-tracing-policy this has to be a one element array for now.
          - `datadog` object: Datadog backend configuration.
            - `splitService` boolean: Determines if datadog service name should be split based on traffic direction and destination. For example, with `splitService: true` and a `backend` service that communicates with a couple of databases, you would get service names like `backend_INBOUND`, `backend_OUTBOUND_db1`, and `backend_OUTBOUND_db2` in Datadog.
            - `url` string, required: Address of Datadog collector, only host and port are allowed (no paths, fragments etc.)
          - `openTelemetry` object: OpenTelemetry backend configuration.
            - `backendRef` object: BackendRef is a reference to a MeshOpenTelemetryBackend resource that defines the collector endpoint. Mutually exclusive with Endpoint.
              - …
            - `endpoint` string: Address of OpenTelemetry collector. Deprecated: use BackendRef instead.
          - `type` 'Zipkin' | 'Datadog' | 'OpenTelemetry', required
          - `zipkin` object: Zipkin backend configuration.
            - `apiVersion` 'httpJson' | 'httpProto': Version of the API. https://github.com/envoyproxy/envoy/blob/v1.22.0/api/envoy/config/trace/v3/zipkin.proto#L66
            - `sharedSpanContext` boolean: Determines whether client and server spans will share the same span context. https://github.com/envoyproxy/envoy/blob/v1.22.0/api/envoy/config/trace/v3/zipkin.proto#L63
            - `traceId128bit` boolean: Generate 128bit traces.
            - `url` string, required: Address of Zipkin collector.
        - `sampling` object: Sampling configuration. Sampling is the process by which a decision is made on whether to process/export a span or not.
          - `client` union: Target percentage of requests that will be force traced if the 'x-client-trace-id' header is set. Mirror of client_sampling in Envoy https://github.com/envoyproxy/envoy/blob/v1.22.0/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#L127-L133 Either int or decimal represented as string. If not specified then the default value is 100.
            - integer
            - string
          - `overall` union: Target percentage of requests will be traced after all other sampling checks have been applied (client, force tracing, random sampling). This field functions as an upper limit on the total configured sampling rate. For instance, setting client to 100 but overall to 1 will result in only 1% of client requests with the appropriate headers to be force traced. Mirror of overall_sampling in Envoy https://github.com/envoyproxy/envoy/blob/v1.22.0/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#L142-L150 Either int or decimal represented as string. If not specified then the default value is 100.
            - integer
            - string
          - `random` union: Target percentage of requests that will be randomly selected for trace generation, if not requested by the client or not forced. Mirror of random_sampling in Envoy https://github.com/envoyproxy/envoy/blob/v1.22.0/api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#L135-L140 Either int or decimal represented as string. If not specified then the default value is 100.
            - integer
            - string
        - `tags` object[]: Custom tags configuration. You can add custom tags to traces based on headers or literal values.
          - `header` object: Tag taken from a header.
            - `default` string: Default value to use if header is missing. If the default is missing and there is no value the tag will not be included.
            - `name` string, required: Name of the header.
          - `literal` string: Tag taken from literal value.
          - `name` string, required: Name of the tag.
      - `targetRef` object: TargetRef is a reference to the resource the policy takes an effect on. The resource could be either a real store object or virtual resource defined inplace.
        - `kind` 'Mesh' | 'MeshSubset' | 'MeshGateway' | 'MeshService' | 'MeshExternalService' | 'MeshMultiZoneService' | 'MeshServiceSubset' | 'MeshHTTPRoute' | 'Dataplane', required: Kind of the referenced resource
        - `labels` object: Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.
        - `mesh` string: Mesh is reserved for future use to identify cross mesh resources.
        - `name` string: Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`
        - `namespace` string: Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.
        - `proxyTypes` string[]: ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.
        - `sectionName` string: SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
        - `tags` object: Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`
    - `creationTime` string, date-time: Time at which the resource was created
    - `modificationTime` string, date-time: Time at which the resource was updated
    - `status` object: Status is the current status of the Kuma MeshTrace resource.
      - `conditions` object[]
        - `message` string, required: message is a human readable message indicating details about the transition. This may be an empty string.
        - `reason` string, required: reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
        - `status` 'True' | 'False' | 'Unknown', required: status of the condition, one of True, False, Unknown.
        - `type` string, required: type of condition in CamelCase or in foo.example.com/CamelCase.
  - `total` number: The total number of entities
  - `next` string: URL to the next page

## Changes

- **2026-08-18** `658ffb748f95`: 2 breaking, 3 info
  - the response property `items/items/spec/default/backends/items/openTelemetry/endpoint` became optional for the status `200`
  - the `items/items/spec/default/backends/items/openTelemetry/endpoint` response property's minLength was decreased from `1` to `0` for the response status `200`
  - added the optional property `items/items/spec/default/backends/items/openTelemetry/backendRef` to the response with the `200` status
  - added the optional property `items/items/status` to the response with the `200` status
  - …1 more
- **2025-11-06** `5d2b35832e3f`: 1 info
  - added the optional property `items/items/kri` to the response with the `200` status

[Operation history](https://skmtc.dev/kong/apis/konnect-api-beta/changes/v1/mesh/control-planes/:cpId/api/meshes/:mesh/meshtraces/get.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api-beta.md) - [All operations](https://skmtc.dev/kong/apis/konnect-api-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-beta/revisions/cef0f947e9c9?raw)