# Diagnostics # Traceroutes ## Traceroute `client.diagnostics.traceroutes.create(TracerouteCreateParamsparams, RequestOptionsoptions?): SinglePage` **post** `/accounts/{account_id}/diagnostics/traceroute` Run traceroutes from Cloudflare colos. ### Parameters - `params: TracerouteCreateParams` - `account_id: string` Path param: Identifier - `targets: Array` Body param - `colos?: Array` Body param: If no source colo names specified, all colos will be used. China colos are unavailable for traceroutes. - `options?: Options` Body param - `max_ttl?: number` Max TTL. - `packet_type?: "icmp" | "tcp" | "udp" | 2 more` Type of packet sent. - `"icmp"` - `"tcp"` - `"udp"` - `"gre"` - `"gre+icmp"` - `packets_per_ttl?: number` Number of packets sent at each TTL. - `port?: number` For UDP and TCP, specifies the destination port. For ICMP, specifies the initial ICMP sequence value. Default value 0 will choose the best value to use for each protocol. - `wait_time?: number` Set the time (in seconds) to wait for a response to a probe. ### Returns - `Traceroute` - `colos?: Array` - `colo?: Colo` - `city?: string` Source colo city. - `name?: string` Source colo name. - `error?: "" | "Could not gather traceroute data: Code 1" | "Could not gather traceroute data: Code 2" | 2 more` Errors resulting from collecting traceroute from colo to target. - `""` - `"Could not gather traceroute data: Code 1"` - `"Could not gather traceroute data: Code 2"` - `"Could not gather traceroute data: Code 3"` - `"Could not gather traceroute data: Code 4"` - `hops?: Array` - `nodes?: Array` An array of node objects. - `asn?: string` AS number associated with the node object. - `ip?: string` IP address of the node. - `labels?: Array` Field appears if there is an additional annotation printed when the probe returns. Field also appears when running a GRE+ICMP traceroute to denote which traceroute a node comes from. - `max_rtt_ms?: number` Maximum RTT in ms. - `mean_rtt_ms?: number` Mean RTT in ms. - `min_rtt_ms?: number` Minimum RTT in ms. - `name?: string` Host name of the address, this may be the same as the IP address. - `packet_count?: number` Number of packets with a response from this node. - `std_dev_rtt_ms?: number` Standard deviation of the RTTs in ms. - `packets_lost?: number` Number of packets where no response was received. - `packets_sent?: number` Number of packets sent with specified TTL. - `packets_ttl?: number` The time to live (TTL). - `target_summary?: unknown` Aggregated statistics from all hops about the target. - `traceroute_time_ms?: number` Total time of traceroute in ms. - `target?: string` The target hostname, IPv6, or IPv6 address. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const traceroute of client.diagnostics.traceroutes.create({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', targets: ['203.0.113.1', 'cloudflare.com'], })) { console.log(traceroute.colos); } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": [ { "colos": [ { "colo": { "city": "Denver, CO, US", "name": "den01" }, "error": "", "hops": [ { "nodes": [ { "asn": "AS13335", "ip": "1.1.1.1", "labels": [ "string" ], "max_rtt_ms": 0, "mean_rtt_ms": 0, "min_rtt_ms": 0, "name": "one.one.one.one", "packet_count": 3, "std_dev_rtt_ms": 0 } ], "packets_lost": 0, "packets_sent": 0, "packets_ttl": 0 } ], "target_summary": { "asn": "", "ip": "1.1.1.1", "max_latency_ms": 0.034, "mean_latency_ms": 0.021, "min_latency_ms": 0.014, "name": "1.1.1.1", "packet_count": 3, "std_dev_latency_ms": 0.011269427669584647 }, "traceroute_time_ms": 0 } ], "target": "1.1.1.1" } ] } ``` ## Domain Types ### Traceroute - `Traceroute` - `colos?: Array` - `colo?: Colo` - `city?: string` Source colo city. - `name?: string` Source colo name. - `error?: "" | "Could not gather traceroute data: Code 1" | "Could not gather traceroute data: Code 2" | 2 more` Errors resulting from collecting traceroute from colo to target. - `""` - `"Could not gather traceroute data: Code 1"` - `"Could not gather traceroute data: Code 2"` - `"Could not gather traceroute data: Code 3"` - `"Could not gather traceroute data: Code 4"` - `hops?: Array` - `nodes?: Array` An array of node objects. - `asn?: string` AS number associated with the node object. - `ip?: string` IP address of the node. - `labels?: Array` Field appears if there is an additional annotation printed when the probe returns. Field also appears when running a GRE+ICMP traceroute to denote which traceroute a node comes from. - `max_rtt_ms?: number` Maximum RTT in ms. - `mean_rtt_ms?: number` Mean RTT in ms. - `min_rtt_ms?: number` Minimum RTT in ms. - `name?: string` Host name of the address, this may be the same as the IP address. - `packet_count?: number` Number of packets with a response from this node. - `std_dev_rtt_ms?: number` Standard deviation of the RTTs in ms. - `packets_lost?: number` Number of packets where no response was received. - `packets_sent?: number` Number of packets sent with specified TTL. - `packets_ttl?: number` The time to live (TTL). - `target_summary?: unknown` Aggregated statistics from all hops about the target. - `traceroute_time_ms?: number` Total time of traceroute in ms. - `target?: string` The target hostname, IPv6, or IPv6 address. # Endpoint Healthchecks ## List Endpoint Health Checks `client.diagnostics.endpointHealthchecks.list(EndpointHealthcheckListParamsparams, RequestOptionsoptions?): EndpointHealthcheckListResponse` **get** `/accounts/{account_id}/diagnostics/endpoint-healthchecks` List Endpoint Health Checks. ### Parameters - `params: EndpointHealthcheckListParams` - `account_id: string` Identifier ### Returns - `EndpointHealthcheckListResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const endpointHealthchecks = await client.diagnostics.endpointHealthchecks.list({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(endpointHealthchecks.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": { "check_type": "icmp", "endpoint": "203.0.113.1", "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "name": "My Endpoint" } } ``` ## Endpoint Health Check `client.diagnostics.endpointHealthchecks.create(EndpointHealthcheckCreateParamsparams, RequestOptionsoptions?): EndpointHealthcheckCreateResponse` **post** `/accounts/{account_id}/diagnostics/endpoint-healthchecks` Create Endpoint Health Check. ### Parameters - `params: EndpointHealthcheckCreateParams` - `account_id: string` Path param: Identifier - `check_type: "icmp"` Body param: type of check to perform - `"icmp"` - `endpoint: string` Body param: the IP address of the host to perform checks against - `name?: string` Body param: Optional name associated with this check ### Returns - `EndpointHealthcheckCreateResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const endpointHealthcheck = await client.diagnostics.endpointHealthchecks.create({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', check_type: 'icmp', endpoint: '203.0.113.1', }); console.log(endpointHealthcheck.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": { "check_type": "icmp", "endpoint": "203.0.113.1", "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "name": "My Endpoint" } } ``` ## Get Endpoint Health Check `client.diagnostics.endpointHealthchecks.get(stringid, EndpointHealthcheckGetParamsparams, RequestOptionsoptions?): EndpointHealthcheckGetResponse` **get** `/accounts/{account_id}/diagnostics/endpoint-healthchecks/{id}` Get a single Endpoint Health Check. ### Parameters - `id: string` UUID. - `params: EndpointHealthcheckGetParams` - `account_id: string` Identifier ### Returns - `EndpointHealthcheckGetResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const endpointHealthcheck = await client.diagnostics.endpointHealthchecks.get( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(endpointHealthcheck.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": { "check_type": "icmp", "endpoint": "203.0.113.1", "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "name": "My Endpoint" } } ``` ## Delete Endpoint Health Check `client.diagnostics.endpointHealthchecks.delete(stringid, EndpointHealthcheckDeleteParamsparams, RequestOptionsoptions?): EndpointHealthcheckDeleteResponse` **delete** `/accounts/{account_id}/diagnostics/endpoint-healthchecks/{id}` Delete Endpoint Health Check. ### Parameters - `id: string` UUID. - `params: EndpointHealthcheckDeleteParams` - `account_id: string` Identifier ### Returns - `EndpointHealthcheckDeleteResponse` - `errors: Array` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` - `messages: Array` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` - `success: true` Whether the API call was successful. - `true` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const endpointHealthcheck = await client.diagnostics.endpointHealthchecks.delete( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(endpointHealthcheck.errors); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true } ``` ## Update Endpoint Health Check `client.diagnostics.endpointHealthchecks.update(stringid, EndpointHealthcheckUpdateParamsparams, RequestOptionsoptions?): EndpointHealthcheckUpdateResponse` **put** `/accounts/{account_id}/diagnostics/endpoint-healthchecks/{id}` Update a Endpoint Health Check. ### Parameters - `id: string` UUID. - `params: EndpointHealthcheckUpdateParams` - `account_id: string` Path param: Identifier - `check_type: "icmp"` Body param: type of check to perform - `"icmp"` - `endpoint: string` Body param: the IP address of the host to perform checks against - `name?: string` Body param: Optional name associated with this check ### Returns - `EndpointHealthcheckUpdateResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const endpointHealthcheck = await client.diagnostics.endpointHealthchecks.update( 'f174e90a-fafe-4643-bbbc-4a0ed4fc8415', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', check_type: 'icmp', endpoint: '203.0.113.1', }, ); console.log(endpointHealthcheck.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": { "check_type": "icmp", "endpoint": "203.0.113.1", "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "name": "My Endpoint" } } ``` ## Domain Types ### Endpoint Healthcheck - `EndpointHealthcheck` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `name?: string` Optional name associated with this check ### Endpoint Healthcheck List Response - `EndpointHealthcheckListResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Endpoint Healthcheck Create Response - `EndpointHealthcheckCreateResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Endpoint Healthcheck Get Response - `EndpointHealthcheckGetResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check ### Endpoint Healthcheck Delete Response - `EndpointHealthcheckDeleteResponse` - `errors: Array` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` - `messages: Array` - `code: number` - `message: string` - `documentation_url?: string` - `source?: Source` - `pointer?: string` - `success: true` Whether the API call was successful. - `true` ### Endpoint Healthcheck Update Response - `EndpointHealthcheckUpdateResponse` - `check_type: "icmp"` type of check to perform - `"icmp"` - `endpoint: string` the IP address of the host to perform checks against - `id?: string` UUID. - `name?: string` Optional name associated with this check