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/