Using the undocumented Fly GraphQL API#

Fly has a GraphQL API which is used by some of their own tools - I found it while browsing around their code on GitHub.

It’s very much undocumented, which means you would be very foolish to write any software against it and expect it to continue to work as Fly make changes.

Only it is kind of documented, because GraphQL introspection provides decent documentation.

(Also it’s used by example code published by Fly, so maybe it’s more supported than I initially thought.)

The endpoint is https://api.fly.io/graphql - you need a Authorization: Bearer xxx HTTP header to access it, where you can get the xxx token by running flyctl auth token.

Or, you can point your browser directly at https://api.fly.io/graphql - they are running a copy of GraphiQL there which provides an interactive explorer plus documentation and schema tabs.

And if you’re signed in to the Fly web interface it will use your .fly.io cookies to authenticate your GraphQL requests - so no need to worry about that Authorization header.

Here’s a query I used to answer the question “what volumes do I have attached, across all of my instances?”

1
{
2
  apps {
3
    nodes {
4
      name
5
      volumes {
6
        nodes {
7
          name
8
        }
9
      }
10
    }
11
  }
12
}

Here’s a much more fun query:

1
{
2
  # Your user account:
3
  viewer {
4
    avatarUrl
5
    createdAt
6
    email
7
    # This returned the following for me:
8
    # ["backend_wordpress", "response_headers_middleware", "firecracker", "dashboard_logs"]
9
    featureFlags
10
  }
11
  nearestRegion {
12
    # This returned "sjc"
13
    code
14
  }
15
  personalOrganization {
16
    name
17
    creditBalance
18
    creditBalanceFormatted
19
    # Not sure what these are but they look interesting - I have 7
20
    loggedCertificates {
21
      totalCount
22
      nodes {
23
        cert
24
        id
25
        root
26
      }
27
    }
28
    isCreditCardSaved
29
    wireGuardPeers {
30
      # Returned one entry for me, with name:
31
      # interactive-Simons-MacBook-Pro-swillison-gmail-com-26
32
      # Presumably the flyctl CLI command set this up
33
      totalCount
34
      nodes {
35
        name
36
        network
37
        peerip
38
        pubkey
39
        region
40
      }
41
    }
42
  }
43
}

This one returns recent logs (only for the past hour / max of 50 values - those are the highest numbers that can be used for those parameters):

1
{
2
  apps {
3
    nodes {
4
      name
5
      vms {
6
        totalCount
7
        nodes {
8
          recentLogs(limit: 50, range: 3600) {
9
            id
10
            region
11
            message
12
            timestamp
13
          }
14
        }
15
      }
16
    }
17
  }
18
}

And another one which digs into the details of attached volumes:

1
{
2
  apps {
3
    nodes {
4
      name
5
      services {
6
        checks {
7
          httpPath
8
          httpMethod
9
          name
10
        }
11
        description
12
      }
13
      volumes {
14
        nodes {
15
          id
16
          name
17
          createdAt
18
          host {
19
            id
20
          }
21
          sizeGb
22
          status
23
          usedBytes
24
          region
25
          app {
26
            name
27
          }
28
          attachedAllocation {
29
            privateIP
30
            # Not sure why attachedAllocation on a volume gives app HTTP traffic logs:
31
            recentLogs {
32
              id
33
              message
34
              timestamp
35
            }
36
            canary
37
            events {
38
              message
39
              timestamp
40
            }
41
          }
42
        }
43
      }
44
    }
45
  }
46
}