Healthchecks

GraphQL Health Checks

Monitor GraphQL endpoints with custom queries, variables, headers, and response validation.

Overview

GraphQL health checks let you monitor your GraphQL API endpoints by executing actual GraphQL queries and validating the responses. Unlike simple HTTP checks that only verify connectivity, GraphQL checks ensure your schema is loaded, resolvers are working, and the endpoint returns valid data.

By default, Uptimy sends a lightweight introspection query ({ __typename }) that works with any GraphQL server. You can customize this to run any query that represents a meaningful health indicator for your application.

Configuration

ParameterDescriptionDefault
Endpoint URLThe full URL of your GraphQL endpointRequired
GraphQL QueryThe GraphQL query to execute{ __typename }
Request headersAdditional HTTP headers (e.g., authentication tokens)Empty
Expected Response Body (JSON)A JSON object of fields the response must contain with the same values. Nested objects are matched the same way, and values are compared as textEmpty

The query, headers and expected response are under Advanced settings in the app. The expected response is matched against the whole response, so it starts at data, for example {"data": {"health": {"status": "ok"}}}.

Custom Queries

You can use any valid GraphQL query to verify the health of your API. Here are some common patterns:

Basic Introspection (Default)

Default Query
{
  __typename
}

This is the simplest possible query. It verifies that the GraphQL server is running, the schema is loaded, and the endpoint can process requests.

Application-Level Health Check

Custom Health Query
query HealthCheck {
  health {
    status
    database
    cache
    version
  }
}

A custom health query can verify that downstream dependencies like databases and caches are also operational.

Query with Variables

The app has no field for variables. Set them as variables in the check's config through the API or uptimyctl:

Query with Variables
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}
Variables
{
  "id": "health-check-user-id"
}

Choose Lightweight Queries

Use the simplest query that gives you confidence your API is working. Heavy queries with deep nesting or large result sets add unnecessary load to your server and increase check duration. The default __typename query is ideal for basic availability monitoring.

Response Data

Each GraphQL health check execution captures the following data:

FieldDescription
HTTP Status CodeThe HTTP status code returned by the endpoint (typically 200 for GraphQL)
GraphQL SuccessBoolean indicating whether the query executed without errors
DNS LookupTime spent resolving the domain name
TCP ConnectionTime to establish the TCP connection
TLS HandshakeTime for the SSL/TLS handshake (HTTPS only)
Time to First ByteTime from request sent to first response byte received
Content TransferTime to download the complete response body

GraphQL Error Handling

GraphQL APIs typically return HTTP 200 even when query errors occur. Uptimy inspects the response body for a GraphQL errors field to accurately determine whether the query succeeded. This prevents false positives that simple HTTP status checks would miss.

Example Configuration

GraphQL is healthcheck type 3. This is its config as the API and uptimyctl take it. The interval and timeout aren't part of it: they are set on the check itself, as intervalSeconds and timeoutSeconds.

GraphQL check config
{
  "uri": "https://api.example.com/graphql",
  "query": "query GetUser($id: ID!) { user(id: $id) { id } }",
  "variables": { "id": "health-check-user-id" },
  "headers": {
    "Authorization": "Bearer your-api-token"
  },
  "expectedResponse": {
    "data": { "user": { "id": "health-check-user-id" } }
  }
}

Authentication

If your GraphQL endpoint requires authentication, add the necessary headers under Request headers. Ensure your monitoring credentials have minimal read-only permissions to follow the principle of least privilege.