Cisco Catalyst Center Thousand Eyes Path Trace API

openapi: 3.2.0
info:
  title: Path traces for ThousandEyes test results Thousand Eyes Path Trace API
  description: APIs related to path trace data of ThousandEyes test results. Data from ThousandEyes is embellished with additional information available from the system to provide more context.
  termsOfService: https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html
  contact:
    name: Cisco TAC World Wide
    url: https://www.cisco.com/c/en/us/support/web/tsd-cisco-worldwide-contacts.html
    email: tac@cisco.com
  license:
    name: Cisco Catalyst Center License
    url: https://www.cisco.com/c/en/us/products/collateral/software/dna-software-ebook-cte.html
  version: 1.0.0
  x-provenance:
    method: harvested
    authored_by: Cisco Catalyst Center
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: developer.cisco.com
    note: 27 Cisco-published OpenAPI 3.0 Assurance documents (185 operations). Ownership confirmed from the tac@cisco.com contact, the Cisco EULA terms-of-service URL and the Cisco Catalyst Center license block carried in each document.
  x-evidence:
  - type: source
    url: https://developer.cisco.com/docs/catalyst-center/
  - type: source
    url: https://developer.cisco.com/dnacenter/
servers:
- url: /
tags:
- name: thousandEyesPathTrace
  description: Operations related to path traces for ThousandEyes test results
paths:
  /dna/data/api/v1/thousandEyesTestResults/{id}/pathTraces:
    get:
      tags:
      - thousandEyesPathTrace
      summary: Retrieves the list of path traces for the given ThousandEyes test result
      description: 'Retrieves the list of path traces for the given ThousandEyes test result.


        Notes:

        * For each trace there would be a list of hops in the path.

        * The hop index starts from 1.

        * It is possible that some hop indexes are missing in the trace. This could happen when details of the hop could not be determined.

        * If `clientMacAddress` parameter is provided, then the trace would start from the given client. But if the given client is not connected to the switch where ThousandEyes agent is running, then the path trace will not be accurate. The path from agent onwards will be correct though.

        * The last hop for each trace would be the target server hop, but in case the trace did not complete (packet lost), then the penultimate hop would have attribute `traceTerminated: true`, and it means that the packet was not forwarded till the target.

        '
      operationId: readThousandEyesTestPathTraces
      parameters:
      - name: id
        in: path
        description: Unique identifier of the test result.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: clientMacAddress
        in: query
        description: 'Optional client MAC address. If this is provided the the path trace would start from the given client, otherwise the path trace starts from the switch where ThousanEyes agent is running.

          '
        required: false
        style: form
        explode: true
        schema:
          pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$|^[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}$
          type: string
      - name: X-CALLER-ID
        in: header
        description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request.

          '
        required: false
        schema:
          type: string
          default: unknown
        example: ui:client360
      responses:
        '200':
          description: Response for the list of ThousandEyes path traces
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ThousandEyesPathTracesResponse'
              examples:
                GreenPathTraceExample:
                  $ref: '#/components/examples/GreenPathTraceExample'
                RedPathTraceExample:
                  $ref: '#/components/examples/RedPathTraceExample'
        '400':
          description: The client made a request that the server could not understand (for example, the request syntax is incorrect).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppxErrorResponse'
        '404':
          description: The client made a request for a resource that does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The server could not fulfill the request due to internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppxErrorResponse'
        1XX:
          description: Informational Responses - The server received the request and sent an informational response.
        2XX:
          description: Successful Responses - The server received the client request, understood it, and accepted it.
        3XX:
          description: Redirection Messages - The client must take additional action to complete the request.
        4XX:
          description: Client Error Responses - The client request caused the error.
        5XX:
          description: Server Error Responses - The server failed to fulfill the request.
  /dna/data/api/v1/thousandEyesTestResults/{id}/pathTraces/count:
    get:
      tags:
      - thousandEyesPathTrace
      summary: Counts the number of path traces for the given ThousandEyes test result
      description: 'Retrieves the count of path traces for the given ThousandEyes test result.

        '
      operationId: countThousandEyesTestPathTraces
      parameters:
      - name: id
        in: path
        description: Unique identifier of the test result.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: clientMacAddress
        in: query
        description: 'Optional client MAC address. If this is provided the the path trace would start from the given client, otherwise the path trace starts from the switch where ThousanEyes agent is running.

          '
        required: false
        style: form
        explode: true
        schema:
          pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$|^[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}$
          type: string
      - name: X-CALLER-ID
        in: header
        description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request.

          '
        required: false
        schema:
          type: string
          default: unknown
        example: ui:client360
      responses:
        '200':
          description: Response for the count of ThousandEyes test results
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/AppxCountIntegerResponse'
        '400':
          description: The client made a request that the server could not understand (for example, the request syntax is incorrect).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppxErrorResponse'
        '404':
          description: The client made a request for a resource that does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The server could not fulfill the request due to internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppxErrorResponse'
        1XX:
          description: Informational Responses - The server received the request and sent an informational response.
        2XX:
          description: Successful Responses - The server received the client request, understood it, and accepted it.
        3XX:
          description: Redirection Messages - The client must take additional action to complete the request.
        4XX:
          description: Client Error Responses - The client request caused the error.
        5XX:
          description: Server Error Responses - The server failed to fulfill the request.
components:
  examples:
    GreenPathTraceExample:
      summary: Green trace starting with client
      value:
        response:
        - id: '5603854460383495258615338483323051590363828340848442984218963750195'
          hops:
          - index: 1
            type: CLIENT
            identifier: 29:1D:FD:29:E0:10
            name: John-Laptop
            ipAddress: 10.233.76.184
            healthScore: 10
          - index: 2
            type: AP
            identifier: 485b492a-7893-4ee7-a0c2-e9645daf75ff
            name: b1-f1-ap3.example.com
            ipAddress: 10.211.85.63
            healthScore: 10
          - index: 3
            type: AGENT
            identifier: 6995d1f2-dd46-4058-8a9e-aea80e8b75b3
            name: b1-access7.example.com
            ipAddress: 10.211.101.102
            jitter: 1.205
            healthScore: 10
          - index: 4
            type: SWITCH
            identifier: 095655ad-a7d9-4da1-92d1-ccd5c6f9e4a2
            name: b1-core3.example.com
            ipAddress: 10.211.101.102
            healthScore: 10
            location: Bengaluru, Karnataka, India
            responseTime: 0
          - index: 5
            type: ROUTER
            identifier: f6073913-013d-4331-b17d-cf3403cad37e
            name: b1-router.example.com
            ipAddress: 10.211.29.11
            healthScore: 10
            location: Bengaluru, Karnataka, India
            network: Example Systems, Inc. (AS 110)
            responseTime: 1
          - index: 6
            type: EXTERNAL
            name: bangdp-33-33.mantraonline.com
            ipAddress: 202.56.248.33
            location: Bengaluru, Karnataka, India
            network: Bharti Airtel Ltd. (AS 9498)
            responseTime: 7
          - index: 12
            type: EXTERNAL
            ipAddress: 142.250.226.43
            location: Los Angeles, California, US
            network: Google Inc. (AS 15169)
            responseTime: 215
          - index: 13
            type: TARGET
            ipAddress: 142.250.68.78
            location: Los Angeles, California, US
            network: Google Inc. (AS 15169)
            responseTime: 215
        appLink: https://app.thousandeyes.com/net/path-vis?__a=123&testId=105&roundId=1747900800&serverId=339&agentId=107
        version: '1.0'
    RedPathTraceExample:
      summary: Trace from agent with packet loss
      value:
        response:
        - id: '5603034966043041906030585277706380995535467971123266443188431236403'
          hops:
          - index: 1
            type: AGENT
            identifier: 6995d1f2-dd46-4058-8a9e-aea80e8b75b3
            name: b1-access7.example.com
            ipAddress: 10.211.101.102
            jitter: 23.59
            healthScore: 9
          - index: 2
            type: SWITCH
            identifier: 095655ad-a7d9-4da1-92d1-ccd5c6f9e4a2
            name: b1-core3.example.com
            ipAddress: 10.211.101.102
            healthScore: 8
            location: Bengaluru, Karnataka, India
            responseTime: 0
          - index: 3
            type: ROUTER
            identifier: f6073913-013d-4331-b17d-cf3403cad37e
            name: b1-router.example.com
            ipAddress: 10.211.29.11
            healthScore: 10
            location: Bengaluru, Karnataka, India
            network: Example Systems, Inc. (AS 110)
            responseTime: 1
          - index: 4
            type: EXTERNAL
            name: bangdp-33-33.mantraonline.com
            ipAddress: 202.56.248.33
            location: Bengaluru, Karnataka, India
            network: Bharti Airtel Ltd. (AS 9498)
            responseTime: 7
          - index: 8
            type: EXTERNAL
            ipAddress: 10.30.128.106
            location: Bengaluru, Karnataka, India
            responseTime: 201
            traceTerminated: true
          - index: 9
            type: TARGET
            ipAddress: 142.250.68.78
            name: server.example.com
        appLink: https://app.thousandeyes.com/net/path-vis?__a=123&testId=105&roundId=1747900125&serverId=98&agentId=100
        version: '1.0'
  schemas:
    ErrorResponse:
      title: Error Response
      type: object
      properties:
        response:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        version:
          type: string
          description: The version of the response
          example: '1.0'
      description: Contains information explaining the error that occured   processing this request.
      example:
        response:
        - errorCode: 2600
          message: Error message
          detail: Error details
      externalDocs:
        description: Error Codes - Cisco DevNet
        url: https://developer.cisco.com/docs/dna-center/#!api-quick-start/error-codes
    AppxCountIntegerResponse_response:
      type: object
      properties:
        count:
          type: integer
          description: The total number of records related to the resource
          format: int64
          example: 1000
    AppxErrorResponse:
      title: Error Response
      type: object
      properties:
        response:
          type: array
          items:
            $ref: '#/components/schemas/AppxErrorObject'
        version:
          type: string
          description: The version of the response
          example: '1.0'
      description: Contains information explaining the error that occured   processing this request.
      example:
        response:
        - errorCode: 2600
          message: Error message
          detail: Error details
      externalDocs:
        description: Error Codes - Cisco DevNet
        url: https://developer.cisco.com/docs/dna-center/#!api-quick-start/error-codes
    AppxErrorObject:
      type: object
      properties:
        errorCode:
          type: integer
          description: Application specific error code returned by the server
        message:
          type: string
          description: Brief message about the error condition
        detail:
          type: string
          description: A more detailed explanation of the error condition the   parameter and its value, that caused the condition and why it caused it.
    ThousandEyesPathTraceHop:
      required:
      - index
      - type
      type: object
      properties:
        index:
          minimum: 1
          type: integer
          description: Hop number in the path. It is possible that some hop numbers are missing in the path. This can happen in case where hop details are not available.
          format: int32
        type:
          type: string
          description: 'Type of the hop.


            | Type       | Description  |

            |------------|--------------|

            | `CLIENT`   | Client node (typically first hop in the path). |

            | `AP`       | Access point, if client is wireless. |

            | `AGENT`    | Switch where ThousandEyes agent is running. |

            | `SWITCH`   | Any other switch within the path. |

            | `ROUTER`   | Router node. |

            | `WLC`      | Wireless controller node. |

            | `EXTERNAL` | Any node which is not managed within the system and is external. Typically, this would be WAN/internet hops. |

            | `TARGET`   | Target server node. |

            | `UNKNOWN`  | Any node which is in-between LAN nodes, but corresponding device was not found in inventory. e.g., a node was there in ThousandEyes path trace between a switch and a router, but system was not able to find any device that owned that IP address. |

            '
          enum:
          - CLIENT
          - AP
          - AGENT
          - SWITCH
          - ROUTER
          - WLC
          - EXTERNAL
          - TARGET
          - UNKNOWN
        identifier:
          type: string
          description: 'Identifier for the node.


            * For client nodes, it would be client MAC address.

            * For internal network device nodes, it would be the network device UUID as per inventory.

            * For external nodes, this attribute will be null.

            '
        name:
          type: string
          description: Name of the node. For internal nodes, the name would be determined by data in inventory. For external nodes, the name would be RDNS lookup value from ThousandEyes trace.
        wlcId:
          type: string
          description: Unique id of the wireless controller. This is applicable only for access point node.
          format: uuid
        ipAddress:
          type: string
          description: IP address of the node.
        location:
          type: string
          description: Location of the node as determined by ThousandEyes trace. This attribute is not applicable for agent node and the nodes before that.
        network:
          type: string
          description: Name of the network as determined by ThousandEyes trace. This attribute is not applicable for agent node and the nodes before that.
        responseTime:
          type: integer
          description: Network response time in milliseconds from the agent till this node. This attribute is not applicable for agent node and the nodes before that.
          format: int32
        jitter:
          type: number
          description: Average jitter in milliseconds. This attribute is available only on the agent node, and it represents the jitter for complete path from the agent to the target.
          format: double
        healthScore:
          maximum: 10
          minimum: 1
          type: integer
          description: Health score of the node. This is applicable only for internal nodes.
          format: int32
        traceTerminated:
          type: boolean
          description: Flag to indicate whether path trace got terminated at this node without reaching the target server. This means that packet was lost at this node. Target server node would be after this node, but packet was not forwarded from this node to the same.
      description: Single hop within a path trace
    ErrorObject:
      type: object
      properties:
        errorCode:
          type: integer
          description: Application specific error code returned by the server
        message:
          type: string
          description: Brief message about the error condition
        detail:
          type: string
          description: A more detailed explanation of the error condition the   parameter and its value, that caused the condition and why it caused it.
    ThousandEyesPathTrace:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the path trace
        hops:
          type: array
          description: List of the hops in the given path trace
          items:
            $ref: '#/components/schemas/ThousandEyesPathTraceHop'
      description: A single ThousandEyes path trace.
    AppxCountIntegerResponse:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/AppxCountIntegerResponse_response'
        version:
          type: string
          description: The version of the response
          example: '1.0'
      description: Count of the results for the given filter
    ThousandEyesPathTracesResponse:
      type: object
      properties:
        response:
          type: array
          description: List of ThousandEyes path traces.
          items:
            $ref: '#/components/schemas/ThousandEyesPathTrace'
        appLink:
          type: string
          description: Direct link to the page for the current path trace in ThousandEyes portal.
        version:
          type: string
          description: The version of the response.
      description: List of ThousandEyes path traces.
externalDocs:
  description: Catalyst Center Developer API resources
  url: https://developer.cisco.com/dnacenter/