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, upti.my 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

Parameter	Description	Default
Endpoint URI	The full URL of your GraphQL endpoint	Required
Query	The GraphQL query to execute	`{ __typename }`
Variables	JSON object of query variables	Empty
Custom Headers	Additional HTTP headers (e.g., authentication tokens)	Empty
Expected Response	A string expected in the response body for validation	Empty

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

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:

Field	Description
HTTP Status Code	The HTTP status code returned by the endpoint (typically 200 for GraphQL)
GraphQL Success	Boolean indicating whether the query executed without errors
DNS Lookup	Time spent resolving the domain name
TCP Connection	Time to establish the TCP connection
TLS Handshake	Time for the SSL/TLS handshake (HTTPS only)
Time to First Byte	Time from request sent to first response byte received
Content Transfer	Time to download the complete response body

ℹ️ GraphQL Error Handling

GraphQL APIs typically return HTTP 200 even when query errors occur. upti.my 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 Check Configuration

{
  "endpoint": "https://api.example.com/graphql",
  "query": "{ __typename }",
  "variables": {},
  "headers": {
    "Authorization": "Bearer your-api-token"
  },
  "expected_response": "__typename",
  "timeout_seconds": 10,
  "interval_seconds": 60
}

⚠️ Authentication

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