# DEX ## Domain Types ### Digital Experience Monitor - `DigitalExperienceMonitor = object { id, default, name }` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` ### Network Path - `NetworkPath = object { slots, sampling }` - `slots: array of object { id, clientToAppRttMs, clientToCfEgressRttMs, 3 more }` - `id: string` API Resource UUID tag. - `clientToAppRttMs: number` Round trip time in ms of the client to app mile - `clientToCfEgressRttMs: number` Round trip time in ms of the client to Cloudflare egress mile - `clientToCfIngressRttMs: number` Round trip time in ms of the client to Cloudflare ingress mile - `timestamp: string` - `clientToIspRttMs: optional number` Round trip time in ms of the client to ISP mile - `sampling: optional object { unit, value }` Specifies the sampling applied, if any, to the slots response. When sampled, results shown represent the first test run to the start of each sampling interval. - `unit: "hours"` - `"hours"` - `value: number` ### Network Path Response - `NetworkPathResponse = object { id, deviceName, interval, 4 more }` - `id: string` API Resource UUID tag. - `deviceName: optional string` - `interval: optional string` The interval at which the Traceroute synthetic application test is set to run. - `kind: optional "traceroute"` - `"traceroute"` - `name: optional string` - `networkPath: optional NetworkPath` - `slots: array of object { id, clientToAppRttMs, clientToCfEgressRttMs, 3 more }` - `id: string` API Resource UUID tag. - `clientToAppRttMs: number` Round trip time in ms of the client to app mile - `clientToCfEgressRttMs: number` Round trip time in ms of the client to Cloudflare egress mile - `clientToCfIngressRttMs: number` Round trip time in ms of the client to Cloudflare ingress mile - `timestamp: string` - `clientToIspRttMs: optional number` Round trip time in ms of the client to ISP mile - `sampling: optional object { unit, value }` Specifies the sampling applied, if any, to the slots response. When sampled, results shown represent the first test run to the start of each sampling interval. - `unit: "hours"` - `"hours"` - `value: number` - `url: optional string` The host of the Traceroute synthetic application test ### Percentiles - `Percentiles = object { p50, p90, p95, p99 }` - `p50: optional number` p50 observed in the time period - `p90: optional number` p90 observed in the time period - `p95: optional number` p95 observed in the time period - `p99: optional number` p99 observed in the time period # WARP Change Events ## List WARP change events. **get** `/accounts/{account_id}/dex/warp-change-events` List WARP configuration and enablement toggle change events by device. ### Path Parameters - `account_id: string` ### Query Parameters - `from: string` Start time for the query in ISO (RFC3339 - ISO 8601) format - `page: number` Page number of paginated results - `per_page: number` Number of items per page - `to: string` End time for the query in ISO (RFC3339 - ISO 8601) format - `account_name: optional string` Filter events by account name. - `config_name: optional string` Filter events by WARP configuration name changed from or to. Applicable to type='config' events only. - `sort_order: optional "ASC" or "DESC"` Sort response by event timestamp. - `"ASC"` - `"DESC"` - `toggle: optional "on" or "off"` Filter events by type toggle value. Applicable to type='toggle' events only. - `"on"` - `"off"` - `type: optional "config" or "toggle"` Filter events by type 'config' or 'toggle' - `"config"` - `"toggle"` ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional array of object { account_name, account_tag, device_id, 6 more } or object { device_id, device_registration, from, 5 more }` - `DigitalExperienceMonitoringWARPToggleChangeEvent = object { account_name, account_tag, device_id, 6 more }` - `account_name: optional string` The account name. - `account_tag: optional string` The public account identifier. - `device_id: optional string` API Resource UUID tag. - `device_registration: optional string` API Resource UUID tag. - `hostname: optional string` The hostname of the machine the event is from - `serial_number: optional string` The serial number of the machine the event is from - `timestamp: optional string` Timestamp in ISO format - `toggle: optional "on" or "off"` The state of the WARP toggle. - `"on"` - `"off"` - `user_email: optional string` Email tied to the device - `DigitalExperienceMonitoringWARPConfigChangeEvent = object { device_id, device_registration, from, 5 more }` - `device_id: optional string` API Resource UUID tag. - `device_registration: optional string` API Resource UUID tag. - `from: optional object { account_name, account_tag, config_name }` - `account_name: optional string` The account name. - `account_tag: optional string` API Resource UUID tag. - `config_name: optional string` The name of the WARP configuration. - `hostname: optional string` The hostname of the machine the event is from - `serial_number: optional string` The serial number of the machine the event is from - `timestamp: optional string` Timestamp in ISO format - `to: optional object { account_name, account_tag, config_name }` - `account_name: optional string` The account name. - `account_tag: optional string` API Resource UUID tag. - `config_name: optional string` The name of the WARP configuration. - `user_email: optional string` Email tied to the device - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/warp-change-events \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": [ { "account_name": "account_name", "account_tag": "account_tag", "device_id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "device_registration": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "hostname": "hostname", "serial_number": "serial_number", "timestamp": "2023-10-11T00:00:00Z", "toggle": "on", "user_email": "user_email" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### WARP Change Event Get Response - `WARPChangeEventGetResponse = array of object { account_name, account_tag, device_id, 6 more } or object { device_id, device_registration, from, 5 more }` - `DigitalExperienceMonitoringWARPToggleChangeEvent = object { account_name, account_tag, device_id, 6 more }` - `account_name: optional string` The account name. - `account_tag: optional string` The public account identifier. - `device_id: optional string` API Resource UUID tag. - `device_registration: optional string` API Resource UUID tag. - `hostname: optional string` The hostname of the machine the event is from - `serial_number: optional string` The serial number of the machine the event is from - `timestamp: optional string` Timestamp in ISO format - `toggle: optional "on" or "off"` The state of the WARP toggle. - `"on"` - `"off"` - `user_email: optional string` Email tied to the device - `DigitalExperienceMonitoringWARPConfigChangeEvent = object { device_id, device_registration, from, 5 more }` - `device_id: optional string` API Resource UUID tag. - `device_registration: optional string` API Resource UUID tag. - `from: optional object { account_name, account_tag, config_name }` - `account_name: optional string` The account name. - `account_tag: optional string` API Resource UUID tag. - `config_name: optional string` The name of the WARP configuration. - `hostname: optional string` The hostname of the machine the event is from - `serial_number: optional string` The serial number of the machine the event is from - `timestamp: optional string` Timestamp in ISO format - `to: optional object { account_name, account_tag, config_name }` - `account_name: optional string` The account name. - `account_tag: optional string` API Resource UUID tag. - `config_name: optional string` The name of the WARP configuration. - `user_email: optional string` Email tied to the device # Commands ## List account commands **get** `/accounts/{account_id}/dex/commands` Retrieves a paginated list of commands issued to devices under the specified account, optionally filtered by time range, device, or other parameters ### Path Parameters - `account_id: string` ### Query Parameters - `page: number` Page number for pagination - `per_page: number` Number of results per page - `command_type: optional string` Optionally filter executed commands by command type - `device_id: optional string` Unique identifier for a device - `from: optional string` Start time for the query in ISO (RFC3339 - ISO 8601) format - `status: optional "PENDING_EXEC" or "PENDING_UPLOAD" or "SUCCESS" or "FAILED"` Optionally filter executed commands by status - `"PENDING_EXEC"` - `"PENDING_UPLOAD"` - `"SUCCESS"` - `"FAILED"` - `to: optional string` End time for the query in ISO (RFC3339 - ISO 8601) format - `user_email: optional string` Email tied to the device ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { commands }` - `commands: optional array of object { id, completed_date, created_date, 6 more }` - `id: optional string` - `completed_date: optional string` - `created_date: optional string` - `device_id: optional string` - `filename: optional string` - `registration_id: optional string` Unique identifier for the device registration - `status: optional string` - `type: optional string` - `user_email: optional string` - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/commands \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "commands": [ { "id": "id", "completed_date": "2019-12-27T18:11:19.117Z", "created_date": "2019-12-27T18:11:19.117Z", "device_id": "device_id", "filename": "filename", "registration_id": "registration_id", "status": "status", "type": "type", "user_email": "user_email" } ] }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Create account commands **post** `/accounts/{account_id}/dex/commands` Initiate commands for up to 10 devices per account ### Path Parameters - `account_id: string` ### Body Parameters - `commands: array of object { command_type, device_id, user_email, 2 more }` List of device-level commands to execute - `command_type: "pcap" or "warp-diag"` Type of command to execute on the device - `"pcap"` - `"warp-diag"` - `device_id: string` Unique identifier for the physical device - `user_email: string` Email tied to the device - `command_args: optional object { interfaces, "max-file-size-mb", "packet-size-bytes", 2 more }` - `interfaces: optional array of "default" or "tunnel"` List of interfaces to capture packets on - `"default"` - `"tunnel"` - `"max-file-size-mb": optional number` Maximum file size (in MB) for the capture file. Specifies the maximum file size of the warp-diag zip artifact that can be uploaded. If the zip artifact exceeds the specified max file size, it will NOT be uploaded - `"packet-size-bytes": optional number` Maximum number of bytes to save for each packet - `"test-all-routes": optional boolean` Test an IP address from all included or excluded ranges. Tests an IP address from all included or excluded ranges. Essentially the same as running 'route get '' and collecting the results. This option may increase the time taken to collect the warp-diag - `"time-limit-min": optional number` Limit on capture duration (in minutes) - `registration_id: optional string` Unique identifier for the device registration. Required for multi-user devices to target the correct user session. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { commands }` - `commands: optional array of object { id, args, device_id, 3 more }` List of created commands - `id: optional string` Unique identifier for the command - `args: optional map[string]` Command arguments - `device_id: optional string` Identifier for the device associated with the command - `registration_id: optional string` Unique identifier for the device registration - `status: optional "PENDING_EXEC" or "PENDING_UPLOAD" or "SUCCESS" or "FAILED"` Current status of the command - `"PENDING_EXEC"` - `"PENDING_UPLOAD"` - `"SUCCESS"` - `"FAILED"` - `type: optional string` Type of the command (e.g., "pcap" or "warp-diag") - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/commands \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ -d '{ "commands": [ { "command_type": "pcap", "device_id": "device_id", "user_email": "user_email" } ] }' ``` #### 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": { "commands": [ { "id": "id", "args": { "foo": "string" }, "device_id": "device_id", "registration_id": "registration_id", "status": "PENDING_EXEC", "type": "type" } ] }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Command List Response - `CommandListResponse = object { commands }` - `commands: optional array of object { id, completed_date, created_date, 6 more }` - `id: optional string` - `completed_date: optional string` - `created_date: optional string` - `device_id: optional string` - `filename: optional string` - `registration_id: optional string` Unique identifier for the device registration - `status: optional string` - `type: optional string` - `user_email: optional string` ### Command Create Response - `CommandCreateResponse = object { commands }` - `commands: optional array of object { id, args, device_id, 3 more }` List of created commands - `id: optional string` Unique identifier for the command - `args: optional map[string]` Command arguments - `device_id: optional string` Identifier for the device associated with the command - `registration_id: optional string` Unique identifier for the device registration - `status: optional "PENDING_EXEC" or "PENDING_UPLOAD" or "SUCCESS" or "FAILED"` Current status of the command - `"PENDING_EXEC"` - `"PENDING_UPLOAD"` - `"SUCCESS"` - `"FAILED"` - `type: optional string` Type of the command (e.g., "pcap" or "warp-diag") # Devices ## List devices eligible for remote captures **get** `/accounts/{account_id}/dex/commands/devices` List devices with WARP client support for remote captures which have been connected in the last 1 hour. ### Path Parameters - `account_id: string` ### Query Parameters - `page: number` Page number of paginated results - `per_page: number` Number of items per page - `search: optional string` Filter devices by name or email ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { devices }` - `devices: optional array of object { deviceId, deviceName, eligible, 7 more }` List of eligible devices - `deviceId: optional string` Device identifier (UUID v4) - `deviceName: optional string` Device identifier (human readable) - `eligible: optional boolean` Whether the device is eligible for remote captures - `ineligibleReason: optional string` If the device is not eligible, the reason why. - `personEmail: optional string` User contact email address - `platform: optional string` Operating system - `registrationId: optional string` Device registration identifier (UUID v4). On multi-user devices, this uniquely identifies a user's registration on the device. - `status: optional string` Network status - `timestamp: optional string` Timestamp in ISO format - `version: optional string` WARP client version - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/commands/devices \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "devices": [ { "deviceId": "deviceId", "deviceName": "deviceName", "eligible": true, "ineligibleReason": "ineligibleReason", "personEmail": "personEmail", "platform": "windows", "registrationId": "registrationId", "status": "connected", "timestamp": "2023-10-11T00:00:00Z", "version": "1.0.0" } ] }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Device List Response - `DeviceListResponse = object { devices }` - `devices: optional array of object { deviceId, deviceName, eligible, 7 more }` List of eligible devices - `deviceId: optional string` Device identifier (UUID v4) - `deviceName: optional string` Device identifier (human readable) - `eligible: optional boolean` Whether the device is eligible for remote captures - `ineligibleReason: optional string` If the device is not eligible, the reason why. - `personEmail: optional string` User contact email address - `platform: optional string` Operating system - `registrationId: optional string` Device registration identifier (UUID v4). On multi-user devices, this uniquely identifies a user's registration on the device. - `status: optional string` Network status - `timestamp: optional string` Timestamp in ISO format - `version: optional string` WARP client version # Downloads ## Download command output file **get** `/accounts/{account_id}/dex/commands/{command_id}/downloads/{filename}` Downloads artifacts for an executed command. Bulk downloads are not supported ### Path Parameters - `account_id: string` - `command_id: string` Unique identifier for a command - `filename: string` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/commands/$COMMAND_ID/downloads/$FILENAME \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` # Quota ## Returns account commands usage, quota, and reset time **get** `/accounts/{account_id}/dex/commands/quota` Retrieves the current quota usage and limits for device commands within a specific account, including the time when the quota will reset ### Path Parameters - `account_id: string` ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { quota, quota_usage, reset_time }` - `quota: number` The remaining number of commands that can be initiated for an account - `quota_usage: number` The number of commands that have been initiated for an account - `reset_time: string` The time when the quota resets - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/commands/quota \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "quota": 0, "quota_usage": 0, "reset_time": "2019-12-27T18:11:19.117Z" }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Quota Get Response - `QuotaGetResponse = object { quota, quota_usage, reset_time }` - `quota: number` The remaining number of commands that can be initiated for an account - `quota_usage: number` The number of commands that have been initiated for an account - `reset_time: string` The time when the quota resets # Colos ## List Cloudflare colos **get** `/accounts/{account_id}/dex/colos` List Cloudflare colos that account's devices were connected to during a time period, sorted by usage starting from the most used colo. Colos without traffic are also returned and sorted alphabetically. ### Path Parameters - `account_id: string` ### Query Parameters - `from: string` Start time for connection period in ISO (RFC3339 - ISO 8601) format - `to: string` End time for connection period in ISO (RFC3339 - ISO 8601) format - `sortBy: optional "fleet-status-usage" or "application-tests-usage"` Type of usage that colos should be sorted by. If unspecified, returns all Cloudflare colos sorted alphabetically. - `"fleet-status-usage"` - `"application-tests-usage"` ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional array of object { airportCode, city, countryCode }` array of colos. - `airportCode: string` Airport code - `city: string` City - `countryCode: string` Country code ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/colos \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": [ { "airportCode": "SFO", "city": "San Francisco", "countryCode": "US" } ] } ``` ## Domain Types ### Colo List Response - `ColoListResponse = object { airportCode, city, countryCode }` - `airportCode: string` Airport code - `city: string` City - `countryCode: string` Country code # Fleet Status ## List fleet status details by dimension **get** `/accounts/{account_id}/dex/fleet-status/live` List details for live (up to 60 minutes) devices using WARP ### Path Parameters - `account_id: string` ### Query Parameters - `since_minutes: number` Number of minutes before current time ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { deviceStats }` - `deviceStats: optional object { byColo, byMode, byPlatform, 3 more }` - `byColo: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byMode: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byPlatform: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byStatus: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byVersion: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `uniqueDevicesTotal: optional number` Number of unique devices ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/fleet-status/live \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "deviceStats": { "byColo": [ { "uniqueDevicesTotal": 0, "value": "value" } ], "byMode": [ { "uniqueDevicesTotal": 0, "value": "value" } ], "byPlatform": [ { "uniqueDevicesTotal": 0, "value": "value" } ], "byStatus": [ { "uniqueDevicesTotal": 0, "value": "value" } ], "byVersion": [ { "uniqueDevicesTotal": 0, "value": "value" } ], "uniqueDevicesTotal": 0 } } } ``` ## List fleet status aggregate details by dimension **get** `/accounts/{account_id}/dex/fleet-status/over-time` List details for devices using WARP, up to 7 days ### Path Parameters - `account_id: string` ### Query Parameters - `from: string` Time range beginning in ISO format - `to: string` Time range end in ISO format - `colo: optional string` Cloudflare colo - `device_id: optional string` Device-specific ID, given as UUID v4 ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { deviceStats }` - `deviceStats: optional object { byMode, byStatus, uniqueDevicesTotal }` - `byMode: optional array of object { timestamp, uniqueDevicesTotal, value }` - `timestamp: optional string` Timestamp in ISO format - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byStatus: optional array of object { timestamp, uniqueDevicesTotal, value }` - `timestamp: optional string` Timestamp in ISO format - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `uniqueDevicesTotal: optional number` Number of unique devices - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/fleet-status/over-time \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "deviceStats": { "byMode": [ { "timestamp": "2023-10-11T00:00:00Z", "uniqueDevicesTotal": 0, "value": "value" } ], "byStatus": [ { "timestamp": "2023-10-11T00:00:00Z", "uniqueDevicesTotal": 0, "value": "value" } ], "uniqueDevicesTotal": 0 } }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Live Stat - `LiveStat = object { uniqueDevicesTotal, value }` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` ### Fleet Status Live Response - `FleetStatusLiveResponse = object { deviceStats }` - `deviceStats: optional object { byColo, byMode, byPlatform, 3 more }` - `byColo: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byMode: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byPlatform: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byStatus: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byVersion: optional array of LiveStat` - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `uniqueDevicesTotal: optional number` Number of unique devices ### Fleet Status Over Time Response - `FleetStatusOverTimeResponse = object { deviceStats }` - `deviceStats: optional object { byMode, byStatus, uniqueDevicesTotal }` - `byMode: optional array of object { timestamp, uniqueDevicesTotal, value }` - `timestamp: optional string` Timestamp in ISO format - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `byStatus: optional array of object { timestamp, uniqueDevicesTotal, value }` - `timestamp: optional string` Timestamp in ISO format - `uniqueDevicesTotal: optional number` Number of unique devices - `value: optional string` - `uniqueDevicesTotal: optional number` Number of unique devices # Devices ## List fleet status devices **get** `/accounts/{account_id}/dex/fleet-status/devices` List details for devices using WARP ### Path Parameters - `account_id: string` ### Query Parameters - `from: string` Time range beginning in ISO format - `page: number` Page number - `per_page: number` Number of results per page - `to: string` Time range end in ISO format - `colo: optional string` Cloudflare colo - `device_id: optional string` Device-specific ID, given as UUID v4 - `mode: optional string` The mode under which the WARP client is run - `platform: optional string` Operating system - `sort_by: optional "colo" or "device_id" or "mode" or 4 more` Dimension to sort results by - `"colo"` - `"device_id"` - `"mode"` - `"platform"` - `"status"` - `"timestamp"` - `"version"` - `source: optional "last_seen" or "hourly" or "raw"` Source: * `hourly` - device details aggregated hourly, up to 7 days prior * `last_seen` - device details, up to 60 minutes prior * `raw` - device details, up to 7 days prior - `"last_seen"` - `"hourly"` - `"raw"` - `status: optional string` Network status - `version: optional string` WARP client version ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional array of object { colo, deviceId, mode, 35 more }` - `colo: string` Cloudflare colo - `deviceId: string` Device identifier (UUID v4) - `mode: string` The mode under which the WARP client is run - `platform: string` Operating system - `status: string` Network status - `timestamp: string` Timestamp in ISO format - `version: string` WARP client version - `alwaysOn: optional boolean` - `batteryCharging: optional boolean` - `batteryCycles: optional number` - `batteryPct: optional number` - `connectionType: optional string` - `cpuPct: optional number` - `cpuPctByApp: optional array of array of object { cpu_pct, name }` - `cpu_pct: optional number` - `name: optional string` - `deviceIpv4: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `deviceIpv6: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `deviceName: optional string` Device identifier (human readable) - `diskReadBps: optional number` - `diskUsagePct: optional number` - `diskWriteBps: optional number` - `dohSubdomain: optional string` - `estimatedLossPct: optional number` - `firewallEnabled: optional boolean` - `gatewayIpv4: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `gatewayIpv6: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `handshakeLatencyMs: optional number` - `ispIpv4: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `ispIpv6: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `metal: optional string` - `networkRcvdBps: optional number` - `networkSentBps: optional number` - `networkSsid: optional string` - `personEmail: optional string` User contact email address - `ramAvailableKb: optional number` - `ramUsedPct: optional number` - `ramUsedPctByApp: optional array of array of object { name, ram_used_pct }` - `name: optional string` - `ram_used_pct: optional number` - `switchLocked: optional boolean` - `wifiStrengthDbm: optional number` - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/fleet-status/devices \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": [ { "colo": "SJC", "deviceId": "deviceId", "mode": "proxy", "platform": "windows", "status": "connected", "timestamp": "2023-10-11T00:00:00Z", "version": "1.0.0", "alwaysOn": true, "batteryCharging": true, "batteryCycles": 0, "batteryPct": 0, "connectionType": "connectionType", "cpuPct": 0, "cpuPctByApp": [ [ { "cpu_pct": 0, "name": "name" } ] ], "deviceIpv4": { "address": "address", "asn": 0, "aso": "aso", "location": { "city": "city", "country_iso": "country_iso", "state_iso": "state_iso", "zip": "zip" }, "netmask": "netmask", "version": "version" }, "deviceIpv6": { "address": "address", "asn": 0, "aso": "aso", "location": { "city": "city", "country_iso": "country_iso", "state_iso": "state_iso", "zip": "zip" }, "netmask": "netmask", "version": "version" }, "deviceName": "deviceName", "diskReadBps": 0, "diskUsagePct": 0, "diskWriteBps": 0, "dohSubdomain": "dohSubdomain", "estimatedLossPct": 0, "firewallEnabled": true, "gatewayIpv4": { "address": "address", "asn": 0, "aso": "aso", "location": { "city": "city", "country_iso": "country_iso", "state_iso": "state_iso", "zip": "zip" }, "netmask": "netmask", "version": "version" }, "gatewayIpv6": { "address": "address", "asn": 0, "aso": "aso", "location": { "city": "city", "country_iso": "country_iso", "state_iso": "state_iso", "zip": "zip" }, "netmask": "netmask", "version": "version" }, "handshakeLatencyMs": 0, "ispIpv4": { "address": "address", "asn": 0, "aso": "aso", "location": { "city": "city", "country_iso": "country_iso", "state_iso": "state_iso", "zip": "zip" }, "netmask": "netmask", "version": "version" }, "ispIpv6": { "address": "address", "asn": 0, "aso": "aso", "location": { "city": "city", "country_iso": "country_iso", "state_iso": "state_iso", "zip": "zip" }, "netmask": "netmask", "version": "version" }, "metal": "metal", "networkRcvdBps": 0, "networkSentBps": 0, "networkSsid": "networkSsid", "personEmail": "personEmail", "ramAvailableKb": 0, "ramUsedPct": 0, "ramUsedPctByApp": [ [ { "name": "name", "ram_used_pct": 0 } ] ], "switchLocked": true, "wifiStrengthDbm": 0 } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Device List Response - `DeviceListResponse = object { colo, deviceId, mode, 35 more }` - `colo: string` Cloudflare colo - `deviceId: string` Device identifier (UUID v4) - `mode: string` The mode under which the WARP client is run - `platform: string` Operating system - `status: string` Network status - `timestamp: string` Timestamp in ISO format - `version: string` WARP client version - `alwaysOn: optional boolean` - `batteryCharging: optional boolean` - `batteryCycles: optional number` - `batteryPct: optional number` - `connectionType: optional string` - `cpuPct: optional number` - `cpuPctByApp: optional array of array of object { cpu_pct, name }` - `cpu_pct: optional number` - `name: optional string` - `deviceIpv4: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `deviceIpv6: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `deviceName: optional string` Device identifier (human readable) - `diskReadBps: optional number` - `diskUsagePct: optional number` - `diskWriteBps: optional number` - `dohSubdomain: optional string` - `estimatedLossPct: optional number` - `firewallEnabled: optional boolean` - `gatewayIpv4: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `gatewayIpv6: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `handshakeLatencyMs: optional number` - `ispIpv4: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `ispIpv6: optional object { address, asn, aso, 3 more }` - `address: optional string` - `asn: optional number` - `aso: optional string` - `location: optional object { city, country_iso, state_iso, zip }` - `city: optional string` - `country_iso: optional string` - `state_iso: optional string` - `zip: optional string` - `netmask: optional string` - `version: optional string` - `metal: optional string` - `networkRcvdBps: optional number` - `networkSentBps: optional number` - `networkSsid: optional string` - `personEmail: optional string` User contact email address - `ramAvailableKb: optional number` - `ramUsedPct: optional number` - `ramUsedPctByApp: optional array of array of object { name, ram_used_pct }` - `name: optional string` - `ram_used_pct: optional number` - `switchLocked: optional boolean` - `wifiStrengthDbm: optional number` # HTTP Tests ## Get details and aggregate metrics for an http test **get** `/accounts/{account_id}/dex/http-tests/{test_id}` Get test details and aggregate performance metrics for an http test for a given time period between 1 hour and 7 days. ### Path Parameters - `account_id: string` - `test_id: string` API Resource UUID tag. ### Query Parameters - `from: string` Start time for aggregate metrics in ISO ms - `interval: "minute" or "hour"` Time interval for aggregate time slots. - `"minute"` - `"hour"` - `to: string` End time for aggregate metrics in ISO ms - `colo: optional string` Optionally filter result stats to a Cloudflare colo. Cannot be used in combination with deviceId param. - `deviceId: optional array of string` Optionally filter result stats to a specific device(s). Cannot be used in combination with colo param. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional HTTPDetails` - `host: optional string` The url of the HTTP synthetic application test - `httpStats: optional object { availabilityPct, dnsResponseTimeMs, httpStatusCode, 3 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `dnsResponseTimeMs: TestStatOverTime` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `httpStatusCode: array of object { status200, status300, status400, 2 more }` - `status200: number` - `status300: number` - `status400: number` - `status500: number` - `timestamp: string` - `resourceFetchTimeMs: TestStatOverTime` - `serverResponseTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period - `httpStatsByColo: optional array of object { availabilityPct, colo, dnsResponseTimeMs, 4 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `colo: string` - `dnsResponseTimeMs: TestStatOverTime` - `httpStatusCode: array of object { status200, status300, status400, 2 more }` - `status200: number` - `status300: number` - `status400: number` - `status500: number` - `timestamp: string` - `resourceFetchTimeMs: TestStatOverTime` - `serverResponseTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period - `interval: optional string` The interval at which the HTTP synthetic application test is set to run. - `kind: optional "http"` - `"http"` - `method: optional string` The HTTP method to use when running the test - `name: optional string` The name of the HTTP synthetic application test - `target_policies: optional array of DigitalExperienceMonitor` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` - `targeted: optional boolean` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/http-tests/$TEST_ID \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "host": "http://example.com", "httpStats": { "availabilityPct": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "dnsResponseTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "httpStatusCode": [ { "status200": 0, "status300": 0, "status400": 0, "status500": 0, "timestamp": "2023-07-16 15:00:00+00" } ], "resourceFetchTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "serverResponseTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "uniqueDevicesTotal": 57 }, "httpStatsByColo": [ { "availabilityPct": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "colo": "DFW", "dnsResponseTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "httpStatusCode": [ { "status200": 0, "status300": 0, "status400": 0, "status500": 0, "timestamp": "2023-07-16 15:00:00+00" } ], "resourceFetchTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "serverResponseTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "uniqueDevicesTotal": 57 } ], "interval": "0h5m0s", "kind": "http", "method": "GET", "name": "Atlassian Sign In Page", "target_policies": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "default": true, "name": "name" } ], "targeted": true } } ``` ## Domain Types ### HTTP Details - `HTTPDetails = object { host, httpStats, httpStatsByColo, 6 more }` - `host: optional string` The url of the HTTP synthetic application test - `httpStats: optional object { availabilityPct, dnsResponseTimeMs, httpStatusCode, 3 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `dnsResponseTimeMs: TestStatOverTime` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `httpStatusCode: array of object { status200, status300, status400, 2 more }` - `status200: number` - `status300: number` - `status400: number` - `status500: number` - `timestamp: string` - `resourceFetchTimeMs: TestStatOverTime` - `serverResponseTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period - `httpStatsByColo: optional array of object { availabilityPct, colo, dnsResponseTimeMs, 4 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `colo: string` - `dnsResponseTimeMs: TestStatOverTime` - `httpStatusCode: array of object { status200, status300, status400, 2 more }` - `status200: number` - `status300: number` - `status400: number` - `status500: number` - `timestamp: string` - `resourceFetchTimeMs: TestStatOverTime` - `serverResponseTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period - `interval: optional string` The interval at which the HTTP synthetic application test is set to run. - `kind: optional "http"` - `"http"` - `method: optional string` The HTTP method to use when running the test - `name: optional string` The name of the HTTP synthetic application test - `target_policies: optional array of DigitalExperienceMonitor` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` - `targeted: optional boolean` # Percentiles ## Get percentiles for an http test **get** `/accounts/{account_id}/dex/http-tests/{test_id}/percentiles` Get percentiles for an http test for a given time period between 1 hour and 7 days. ### Path Parameters - `account_id: string` - `test_id: string` API Resource UUID tag. ### Query Parameters - `from: string` Start time for the query in ISO (RFC3339 - ISO 8601) format - `to: string` End time for the query in ISO (RFC3339 - ISO 8601) format - `colo: optional string` Optionally filter result stats to a Cloudflare colo. Cannot be used in combination with deviceId param. - `deviceId: optional array of string` Optionally filter result stats to a specific device(s). Cannot be used in combination with colo param. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional HTTPDetailsPercentiles` - `dnsResponseTimeMs: optional Percentiles` - `p50: optional number` p50 observed in the time period - `p90: optional number` p90 observed in the time period - `p95: optional number` p95 observed in the time period - `p99: optional number` p99 observed in the time period - `resourceFetchTimeMs: optional Percentiles` - `serverResponseTimeMs: optional Percentiles` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/http-tests/$TEST_ID/percentiles \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "dnsResponseTimeMs": { "p50": 0, "p90": 0, "p95": 0, "p99": 0 }, "resourceFetchTimeMs": { "p50": 0, "p90": 0, "p95": 0, "p99": 0 }, "serverResponseTimeMs": { "p50": 0, "p90": 0, "p95": 0, "p99": 0 } } } ``` ## Domain Types ### HTTP Details Percentiles - `HTTPDetailsPercentiles = object { dnsResponseTimeMs, resourceFetchTimeMs, serverResponseTimeMs }` - `dnsResponseTimeMs: optional Percentiles` - `p50: optional number` p50 observed in the time period - `p90: optional number` p90 observed in the time period - `p95: optional number` p95 observed in the time period - `p99: optional number` p99 observed in the time period - `resourceFetchTimeMs: optional Percentiles` - `serverResponseTimeMs: optional Percentiles` ### Test Stat Over Time - `TestStatOverTime = object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period # Tests ## List DEX test analytics **get** `/accounts/{account_id}/dex/tests/overview` List DEX tests with overview metrics ### Path Parameters - `account_id: string` ### Query Parameters - `colo: optional string` Optionally filter result stats to a Cloudflare colo. Cannot be used in combination with deviceId param. - `deviceId: optional array of string` Optionally filter result stats to a specific device(s). Cannot be used in combination with colo param. - `kind: optional "http" or "traceroute"` Filter by test type - `"http"` - `"traceroute"` - `page: optional number` Page number of paginated results - `per_page: optional number` Number of items per page - `testName: optional string` Optionally filter results by test name ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional Tests` - `overviewMetrics: object { testsTotal, avgHttpAvailabilityPct, avgTracerouteAvailabilityPct }` - `testsTotal: number` number of tests. - `avgHttpAvailabilityPct: optional number` percentage availability for all HTTP test results in response - `avgTracerouteAvailabilityPct: optional number` percentage availability for all traceroutes results in response - `tests: array of object { id, created, description, 13 more }` array of test results objects. - `id: string` API Resource UUID tag. - `created: string` date the test was created. - `description: string` the test description defined during configuration - `enabled: boolean` if true, then the test will run on targeted devices. Else, the test will not run. - `host: string` - `interval: string` The interval at which the synthetic application test is set to run. - `kind: "http" or "traceroute"` test type, http or traceroute - `"http"` - `"traceroute"` - `name: string` name given to this test - `updated: string` - `httpResults: optional object { resourceFetchTime }` - `resourceFetchTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `units: "hours" or "days" or "testRuns"` - `"hours"` - `"days"` - `"testRuns"` - `value: number` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` - `httpResultsByColo: optional array of object { colo, resourceFetchTime }` - `colo: string` Cloudflare colo - `resourceFetchTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` - `method: optional string` for HTTP, the method to use when running the test - `target_policies: optional array of DigitalExperienceMonitor` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` - `targeted: optional boolean` - `tracerouteResults: optional object { roundTripTime }` - `roundTripTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` - `tracerouteResultsByColo: optional array of object { colo, roundTripTime }` - `colo: string` Cloudflare colo - `roundTripTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/tests/overview \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "overviewMetrics": { "testsTotal": 0, "avgHttpAvailabilityPct": 0, "avgTracerouteAvailabilityPct": 0 }, "tests": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created": "created", "description": "description", "enabled": true, "host": "host", "interval": "interval", "kind": "http", "name": "name", "updated": "updated", "httpResults": { "resourceFetchTime": { "history": [ { "timePeriod": { "units": "hours", "value": 0 }, "avgMs": 0, "deltaPct": 0 } ], "avgMs": 0, "overTime": { "timePeriod": { "units": "hours", "value": 0 }, "values": [ { "avgMs": 0, "timestamp": "timestamp" } ] } } }, "httpResultsByColo": [ { "colo": "SJC", "resourceFetchTime": { "history": [ { "timePeriod": { "units": "hours", "value": 0 }, "avgMs": 0, "deltaPct": 0 } ], "avgMs": 0, "overTime": { "timePeriod": { "units": "hours", "value": 0 }, "values": [ { "avgMs": 0, "timestamp": "timestamp" } ] } } } ], "method": "method", "target_policies": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "default": true, "name": "name" } ], "targeted": true, "tracerouteResults": { "roundTripTime": { "history": [ { "timePeriod": { "units": "hours", "value": 0 }, "avgMs": 0, "deltaPct": 0 } ], "avgMs": 0, "overTime": { "timePeriod": { "units": "hours", "value": 0 }, "values": [ { "avgMs": 0, "timestamp": "timestamp" } ] } } }, "tracerouteResultsByColo": [ { "colo": "SJC", "roundTripTime": { "history": [ { "timePeriod": { "units": "hours", "value": 0 }, "avgMs": 0, "deltaPct": 0 } ], "avgMs": 0, "overTime": { "timePeriod": { "units": "hours", "value": 0 }, "values": [ { "avgMs": 0, "timestamp": "timestamp" } ] } } } ] } ] } } ``` ## Domain Types ### Aggregate Time Period - `AggregateTimePeriod = object { units, value }` - `units: "hours" or "days" or "testRuns"` - `"hours"` - `"days"` - `"testRuns"` - `value: number` ### Tests - `Tests = object { overviewMetrics, tests }` - `overviewMetrics: object { testsTotal, avgHttpAvailabilityPct, avgTracerouteAvailabilityPct }` - `testsTotal: number` number of tests. - `avgHttpAvailabilityPct: optional number` percentage availability for all HTTP test results in response - `avgTracerouteAvailabilityPct: optional number` percentage availability for all traceroutes results in response - `tests: array of object { id, created, description, 13 more }` array of test results objects. - `id: string` API Resource UUID tag. - `created: string` date the test was created. - `description: string` the test description defined during configuration - `enabled: boolean` if true, then the test will run on targeted devices. Else, the test will not run. - `host: string` - `interval: string` The interval at which the synthetic application test is set to run. - `kind: "http" or "traceroute"` test type, http or traceroute - `"http"` - `"traceroute"` - `name: string` name given to this test - `updated: string` - `httpResults: optional object { resourceFetchTime }` - `resourceFetchTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `units: "hours" or "days" or "testRuns"` - `"hours"` - `"days"` - `"testRuns"` - `value: number` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` - `httpResultsByColo: optional array of object { colo, resourceFetchTime }` - `colo: string` Cloudflare colo - `resourceFetchTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` - `method: optional string` for HTTP, the method to use when running the test - `target_policies: optional array of DigitalExperienceMonitor` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` - `targeted: optional boolean` - `tracerouteResults: optional object { roundTripTime }` - `roundTripTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` - `tracerouteResultsByColo: optional array of object { colo, roundTripTime }` - `colo: string` Cloudflare colo - `roundTripTime: object { history, avgMs, overTime }` - `history: array of object { timePeriod, avgMs, deltaPct }` - `timePeriod: AggregateTimePeriod` - `avgMs: optional number` - `deltaPct: optional number` - `avgMs: optional number` - `overTime: optional object { timePeriod, values }` - `timePeriod: AggregateTimePeriod` - `values: array of object { avgMs, timestamp }` - `avgMs: number` - `timestamp: string` # Unique Devices ## Get count of devices targeted **get** `/accounts/{account_id}/dex/tests/unique-devices` Returns unique count of devices that have run synthetic application monitoring tests in the past 7 days. ### Path Parameters - `account_id: string` ### Query Parameters - `deviceId: optional array of string` Optionally filter result stats to a specific device(s). Cannot be used in combination with colo param. - `testName: optional string` Optionally filter results by test name ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional UniqueDevices` - `uniqueDevicesTotal: number` total number of unique devices ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/tests/unique-devices \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "uniqueDevicesTotal": 0 } } ``` ## Domain Types ### Unique Devices - `UniqueDevices = object { uniqueDevicesTotal }` - `uniqueDevicesTotal: number` total number of unique devices # Traceroute Test Results # Network Path ## Get details for a specific traceroute test run **get** `/accounts/{account_id}/dex/traceroute-test-results/{test_result_id}/network-path` Get a breakdown of hops and performance metrics for a specific traceroute test run ### Path Parameters - `account_id: string` - `test_result_id: string` API Resource UUID tag. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { hops, resultId, deviceName, 2 more }` - `hops: array of object { ttl, asn, aso, 6 more }` an array of the hops taken by the device to reach the end destination - `ttl: number` - `asn: optional number` - `aso: optional string` - `ipAddress: optional string` - `location: optional object { city, state, zip }` - `city: optional string` - `state: optional string` - `zip: optional string` - `mile: optional "client-to-app" or "client-to-cf-egress" or "client-to-cf-ingress" or "client-to-isp"` - `"client-to-app"` - `"client-to-cf-egress"` - `"client-to-cf-ingress"` - `"client-to-isp"` - `name: optional string` - `packetLossPct: optional number` - `rttMs: optional number` - `resultId: string` API Resource UUID tag. - `deviceName: optional string` name of the device associated with this network path response - `testId: optional string` API Resource UUID tag. - `testName: optional string` name of the tracroute test ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/traceroute-test-results/$TEST_RESULT_ID/network-path \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "hops": [ { "ttl": 0, "asn": 0, "aso": "aso", "ipAddress": "ipAddress", "location": { "city": "city", "state": "state", "zip": "zip" }, "mile": "client-to-app", "name": "name", "packetLossPct": 0, "rttMs": 0 } ], "resultId": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "deviceName": "deviceName", "testId": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "testName": "testName" } } ``` ## Domain Types ### Network Path Get Response - `NetworkPathGetResponse = object { hops, resultId, deviceName, 2 more }` - `hops: array of object { ttl, asn, aso, 6 more }` an array of the hops taken by the device to reach the end destination - `ttl: number` - `asn: optional number` - `aso: optional string` - `ipAddress: optional string` - `location: optional object { city, state, zip }` - `city: optional string` - `state: optional string` - `zip: optional string` - `mile: optional "client-to-app" or "client-to-cf-egress" or "client-to-cf-ingress" or "client-to-isp"` - `"client-to-app"` - `"client-to-cf-egress"` - `"client-to-cf-ingress"` - `"client-to-isp"` - `name: optional string` - `packetLossPct: optional number` - `rttMs: optional number` - `resultId: string` API Resource UUID tag. - `deviceName: optional string` name of the device associated with this network path response - `testId: optional string` API Resource UUID tag. - `testName: optional string` name of the tracroute test # Traceroute Tests ## Get details and aggregate metrics for a traceroute test **get** `/accounts/{account_id}/dex/traceroute-tests/{test_id}` Get test details and aggregate performance metrics for an traceroute test for a given time period between 1 hour and 7 days. ### Path Parameters - `account_id: string` - `test_id: string` API Resource UUID tag. ### Query Parameters - `from: string` Start time for aggregate metrics in ISO ms - `interval: "minute" or "hour"` Time interval for aggregate time slots. - `"minute"` - `"hour"` - `to: string` End time for aggregate metrics in ISO ms - `colo: optional string` Optionally filter result stats to a Cloudflare colo. Cannot be used in combination with deviceId param. - `deviceId: optional array of string` Optionally filter result stats to a specific device(s). Cannot be used in combination with colo param. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional Traceroute` - `host: string` The host of the Traceroute synthetic application test - `interval: string` The interval at which the Traceroute synthetic application test is set to run. - `kind: "traceroute"` - `"traceroute"` - `name: string` The name of the Traceroute synthetic application test - `target_policies: optional array of DigitalExperienceMonitor` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` - `targeted: optional boolean` - `tracerouteStats: optional object { availabilityPct, hopsCount, packetLossPct, 2 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `hopsCount: TestStatOverTime` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `packetLossPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `roundTripTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period - `tracerouteStatsByColo: optional array of object { availabilityPct, colo, hopsCount, 3 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `colo: string` - `hopsCount: TestStatOverTime` - `packetLossPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `roundTripTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/traceroute-tests/$TEST_ID \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "host": "1.1.1.1", "interval": "0h5m0s", "kind": "traceroute", "name": "Atlassian Sign In Page", "target_policies": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "default": true, "name": "name" } ], "targeted": true, "tracerouteStats": { "availabilityPct": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "hopsCount": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "packetLossPct": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "roundTripTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "uniqueDevicesTotal": 57 }, "tracerouteStatsByColo": [ { "availabilityPct": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "colo": "DFW", "hopsCount": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "packetLossPct": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "roundTripTimeMs": { "slots": [ { "timestamp": "2023-07-16 15:00:00+00", "value": 0 } ], "avg": 0, "max": 0, "min": 0 }, "uniqueDevicesTotal": 57 } ] } } ``` ## Get percentiles for a traceroute test **get** `/accounts/{account_id}/dex/traceroute-tests/{test_id}/percentiles` Get percentiles for a traceroute test for a given time period between 1 hour and 7 days. ### Path Parameters - `account_id: string` - `test_id: string` API Resource UUID tag. ### Query Parameters - `from: string` Start time for the query in ISO (RFC3339 - ISO 8601) format - `to: string` End time for the query in ISO (RFC3339 - ISO 8601) format - `colo: optional string` Optionally filter result stats to a Cloudflare colo. Cannot be used in combination with deviceId param. - `deviceId: optional array of string` Optionally filter result stats to a specific device(s). Cannot be used in combination with colo param. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { hopsCount, packetLossPct, roundTripTimeMs }` - `hopsCount: optional Percentiles` - `p50: optional number` p50 observed in the time period - `p90: optional number` p90 observed in the time period - `p95: optional number` p95 observed in the time period - `p99: optional number` p99 observed in the time period - `packetLossPct: optional Percentiles` - `roundTripTimeMs: optional Percentiles` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/traceroute-tests/$TEST_ID/percentiles \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "hopsCount": { "p50": 0, "p90": 0, "p95": 0, "p99": 0 }, "packetLossPct": { "p50": 0, "p90": 0, "p95": 0, "p99": 0 }, "roundTripTimeMs": { "p50": 0, "p90": 0, "p95": 0, "p99": 0 } } } ``` ## Get network path breakdown for a traceroute test **get** `/accounts/{account_id}/dex/traceroute-tests/{test_id}/network-path` Get a breakdown of metrics by hop for individual traceroute test runs ### Path Parameters - `account_id: string` - `test_id: string` API Resource UUID tag. ### Query Parameters - `deviceId: string` Device to filter tracroute result runs to - `from: string` Start time for aggregate metrics in ISO ms - `interval: "minute" or "hour"` Time interval for aggregate time slots. - `"minute"` - `"hour"` - `to: string` End time for aggregate metrics in ISO ms ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional NetworkPathResponse` - `id: string` API Resource UUID tag. - `deviceName: optional string` - `interval: optional string` The interval at which the Traceroute synthetic application test is set to run. - `kind: optional "traceroute"` - `"traceroute"` - `name: optional string` - `networkPath: optional NetworkPath` - `slots: array of object { id, clientToAppRttMs, clientToCfEgressRttMs, 3 more }` - `id: string` API Resource UUID tag. - `clientToAppRttMs: number` Round trip time in ms of the client to app mile - `clientToCfEgressRttMs: number` Round trip time in ms of the client to Cloudflare egress mile - `clientToCfIngressRttMs: number` Round trip time in ms of the client to Cloudflare ingress mile - `timestamp: string` - `clientToIspRttMs: optional number` Round trip time in ms of the client to ISP mile - `sampling: optional object { unit, value }` Specifies the sampling applied, if any, to the slots response. When sampled, results shown represent the first test run to the start of each sampling interval. - `unit: "hours"` - `"hours"` - `value: number` - `url: optional string` The host of the Traceroute synthetic application test ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/traceroute-tests/$TEST_ID/network-path \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "deviceName": "deviceName", "interval": "0h5m0s", "kind": "traceroute", "name": "name", "networkPath": { "slots": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "clientToAppRttMs": 0, "clientToCfEgressRttMs": 0, "clientToCfIngressRttMs": 0, "timestamp": "2023-07-16 15:00:00+00", "clientToIspRttMs": 0 } ], "sampling": { "unit": "hours", "value": 0 } }, "url": "1.1.1.1" } } ``` ## Domain Types ### Traceroute - `Traceroute = object { host, interval, kind, 5 more }` - `host: string` The host of the Traceroute synthetic application test - `interval: string` The interval at which the Traceroute synthetic application test is set to run. - `kind: "traceroute"` - `"traceroute"` - `name: string` The name of the Traceroute synthetic application test - `target_policies: optional array of DigitalExperienceMonitor` - `id: string` API Resource UUID tag. - `default: boolean` Whether the policy is the default for the account - `name: string` - `targeted: optional boolean` - `tracerouteStats: optional object { availabilityPct, hopsCount, packetLossPct, 2 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `hopsCount: TestStatOverTime` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `packetLossPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `roundTripTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period - `tracerouteStatsByColo: optional array of object { availabilityPct, colo, hopsCount, 3 more }` - `availabilityPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `colo: string` - `hopsCount: TestStatOverTime` - `packetLossPct: object { slots, avg, max, min }` - `slots: array of object { timestamp, value }` - `timestamp: string` - `value: number` - `avg: optional number` average observed in the time period - `max: optional number` highest observed in the time period - `min: optional number` lowest observed in the time period - `roundTripTimeMs: TestStatOverTime` - `uniqueDevicesTotal: number` Count of unique devices that have run this test in the given time period ### Traceroute Test Percentiles Response - `TracerouteTestPercentilesResponse = object { hopsCount, packetLossPct, roundTripTimeMs }` - `hopsCount: optional Percentiles` - `p50: optional number` p50 observed in the time period - `p90: optional number` p90 observed in the time period - `p95: optional number` p95 observed in the time period - `p99: optional number` p99 observed in the time period - `packetLossPct: optional Percentiles` - `roundTripTimeMs: optional Percentiles` # Rules ## Get DEX Rule **get** `/accounts/{account_id}/dex/rules/{rule_id}` Get details for a DEX Rule ### Path Parameters - `account_id: string` - `rule_id: string` API Resource UUID tag. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/rules/$RULE_ID \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2023-07-16 15:00:00+00", "match": "match", "name": "name", "description": "description", "targeted_tests": [ { "data": { "host": "https://dash.cloudflare.com", "kind": "http", "method": "GET" }, "enabled": true, "name": "name", "test_id": "test_id" } ], "updated_at": "2023-07-16 15:00:00+00" } } ``` ## Delete a DEX Rule **delete** `/accounts/{account_id}/dex/rules/{rule_id}` Delete a DEX Rule ### Path Parameters - `account_id: string` - `rule_id: string` API Resource UUID tag. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional boolean` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/rules/$RULE_ID \ -X DELETE \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": true } ``` ## Update a DEX Rule **patch** `/accounts/{account_id}/dex/rules/{rule_id}` Update a DEX Rule ### Path Parameters - `account_id: string` - `rule_id: string` API Resource UUID tag. ### Body Parameters - `description: optional string` - `match: optional string` The wirefilter expression to match. - `name: optional string` The name of the Rule. ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/rules/$RULE_ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ -d '{}' ``` #### 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": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2023-07-16 15:00:00+00", "match": "match", "name": "name", "description": "description", "targeted_tests": [ { "data": { "host": "https://dash.cloudflare.com", "kind": "http", "method": "GET" }, "enabled": true, "name": "name", "test_id": "test_id" } ], "updated_at": "2023-07-16 15:00:00+00" } } ``` ## Create a DEX Rule **post** `/accounts/{account_id}/dex/rules` Create a DEX Rule ### Path Parameters - `account_id: string` ### Body Parameters - `match: string` The wirefilter expression to match. - `name: string` The name of the Rule. - `description: optional string` ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/rules \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ -d '{ "match": "match", "name": "name" }' ``` #### 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": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2023-07-16 15:00:00+00", "match": "match", "name": "name", "description": "description", "targeted_tests": [ { "data": { "host": "https://dash.cloudflare.com", "kind": "http", "method": "GET" }, "enabled": true, "name": "name", "test_id": "test_id" } ], "updated_at": "2023-07-16 15:00:00+00" } } ``` ## List DEX Rules **get** `/accounts/{account_id}/dex/rules` List DEX Rules ### Path Parameters - `account_id: string` ### Query Parameters - `page: number` Page number of paginated results - `per_page: number` Number of items per page - `name: optional string` Filter results by rule name - `sort_by: optional "name" or "created_at" or "updated_at"` Which property to sort results by - `"name"` - `"created_at"` - `"updated_at"` - `sort_order: optional "ASC" or "DESC"` Sort direction for sort_by property - `"ASC"` - `"DESC"` ### Returns - `errors: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `messages: array of object { code, message, documentation_url, source }` - `code: number` - `message: string` - `documentation_url: optional string` - `source: optional object { pointer }` - `pointer: optional string` - `success: true` Whether the API call was successful. - `true` - `result: optional object { rules }` - `rules: optional array of object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` - `result_info: optional object { count, page, per_page, 2 more }` - `count: optional number` Total number of results for the requested service. - `page: optional number` Current page within paginated list of results. - `per_page: optional number` Number of results per page of results. - `total_count: optional number` Total results available without any search parameters. - `total_pages: optional number` The number of total pages in the entire result set. ### Example ```http curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dex/rules \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` #### 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": { "rules": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2023-07-16 15:00:00+00", "match": "match", "name": "name", "description": "description", "targeted_tests": [ { "data": { "host": "https://dash.cloudflare.com", "kind": "http", "method": "GET" }, "enabled": true, "name": "name", "test_id": "test_id" } ], "updated_at": "2023-07-16 15:00:00+00" } ] }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Rule Get Response - `RuleGetResponse = object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` ### Rule Delete Response - `RuleDeleteResponse = boolean` ### Rule Update Response - `RuleUpdateResponse = object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` ### Rule Create Response - `RuleCreateResponse = object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string` ### Rule List Response - `RuleListResponse = object { rules }` - `rules: optional array of object { id, created_at, match, 4 more }` - `id: string` API Resource UUID tag. - `created_at: string` - `match: string` - `name: string` - `description: optional string` - `targeted_tests: optional array of object { data, enabled, name, test_id }` - `data: object { host, kind, method }` The configuration object which contains the details for the WARP client to conduct the test. - `host: string` The desired endpoint to test. - `kind: "http" or "traceroute"` The type of test. - `"http"` - `"traceroute"` - `method: optional "GET"` The HTTP request method type. - `"GET"` - `enabled: boolean` - `name: string` - `test_id: string` - `updated_at: optional string`