Skip to content
Cloudflare Docs

Query Magic Transit tunnel health check results with GraphQL

This example uses the GraphQL Analytics API to query Magic Transit tunnel health check results. These results are aggregated from individual health checks that Cloudflare servers perform against Generic Routing Encapsulation (GRE) tunnels you configured to work with Magic Transit during onboarding. You can query up to one week of data for dates up to three months in the past.

The following API call requests tunnel health checks for a specific account over a one-day period for a specific Cloudflare data center and outputs the requested fields. Replace <CLOUDFLARE_ACCOUNT_TAG> and <API_TOKEN>1 with your API credentials, and adjust the datetimeStart and datetimeEnd variables as needed.

The API call returns tunnel health check results by Cloudflare data center. Each data center's result is aggregated from health checks conducted on individual servers. The tunnelState field represents the state of the tunnel. Magic Transit uses these states for routing. A tunnelState value of 0 represents a down tunnel, 0.5 represents a degraded tunnel, and 1 represents a healthy tunnel.

API Call

Terminal window
echo '{ "query":
  "query GetTunnelHealthCheckResults($accountTag: string, $datetimeStart: string, $datetimeEnd: string) {
    viewer {
      accounts(filter: {accountTag: $accountTag}) {
        magicTransitTunnelHealthChecksAdaptiveGroups(
          limit: 100,
          filter: {
            datetime_geq: $datetimeStart,
            datetime_lt:  $datetimeEnd,
          }
        ) {
          avg {
            tunnelState
          }
          dimensions {
            tunnelName
            edgeColoName
          }
        }
      }
    }
  }",
  "variables": {
    "accountTag": "<CLOUDFLARE_ACCOUNT_TAG>",
    "datetimeStart": "2022-08-04T00:00:00.000Z",
    "datetimeEnd": "2022-08-04T01:00:00.000Z"
  }
}' | tr -d '\n' | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @-

The results are returned in JSON (as requested), so piping the output to jq makes them easier to read, as in the following example:

Terminal window
... | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @- | jq .


## Example response:
#=> {
#=>   "data": {
#=>     "viewer": {
#=>       "accounts": [
#=>         {
#=>           "conduitEdgeTunnelHealthChecks": [
#=>             {
#=>               {
#=>                 "avg": {
#=>                   "tunnelState": 1
#=>                 },
#=>                 "dimensions": {
#=>                   "edgeColoName": "mel01",
#=>                   "tunnelName": "tunnel_01",
#=>                   "tunnelState": 0.5
#=>                 }
#=>               },
#=>               {
#=>                 "avg": {
#=>                   "tunnelState": 0.5
#=>                 },
#=>                 "count": 310,
#=>                 "dimensions": {
#=>                   "edgeColoName": "mel01",
#=>                   "tunnelName": "tunnel_02",
#=>                   "tunnelState": 0.5
#=>                 }
#=>               }
#=>           ]
#=>         }
#=>       ]
#=>     }
#=>   },
#=>   "errors": null
#=> }

Footnotes

  1. Refer to Configure an Analytics API token for more information on configuration and permissions. ↩