Subgraphs: Monitor sync health

Detect stale data before it reaches your users. Run a small _meta query on a schedule, or add _meta to important reads, to see which deployment served the request, how far it has indexed, and whether it reports indexing errors.

Prerequisites

A Subgraphs API key.
A query endpoint using a Deployment CID, Graph Network Subgraph ID, or Endpoint Alias.
A place to record health-check results, such as application logs or metrics.
For lag alerts, a reliable source of the chain head for the same network.

Request

curl "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>" \
  -H "Authorization: Bearer <GRAPHOPS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query SyncHealth { _meta { deployment block { number hash } hasIndexingErrors } }",
    "operationName": "SyncHealth"
  }'

const response = await fetch(
  "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <GRAPHOPS_API_KEY>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        query SyncHealth {
          _meta {
            deployment
            block { number hash }
            hasIndexingErrors
          }
        }
      `,
      operationName: "SyncHealth",
    }),
  },
);

const result = await response.json();
console.log(result.data._meta);

import { GraphQLClient, gql } from "graphql-request";

const client = new GraphQLClient(
  "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>",
  {
    headers: {
      Authorization: "Bearer <GRAPHOPS_API_KEY>",
    },
  },
);

const query = gql`
  query SyncHealth {
    _meta {
      deployment
      block { number hash }
      hasIndexingErrors
    }
  }
`;

const result = await client.request(query);
console.log(result._meta);

import requests

response = requests.post(
    "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>",
    headers={
        "Authorization": "Bearer <GRAPHOPS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "query": """
        query SyncHealth {
          _meta {
            deployment
            block { number hash }
            hasIndexingErrors
          }
        }
        """,
        "operationName": "SyncHealth",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"]["_meta"])

Response

{  "data": {    "_meta": {      "deployment": "Qm...",The deployment that served this request      "block": {        "number": 18000000,Highest indexed block; track it over time        "hash": "0x..."Include in support requests      },      "hasIndexingErrors": falseAlert when true    }  }}

An illustrative health check. Record all four values on each run so you can spot lag, an unexpected deployment, or indexing errors.

Act on each signal

_metadeployment: "Qm…7c2e"block.number: 18000000block.hash: "0x…"hasIndexingErrors: false

01hasIndexingErrors is trueAlert and check results before you rely on themAlert
02deployment is not the CID you expectCheck the Endpoint Alias target or the owner's latest releaseInvestigate
03block.number stops advancing or falls behind your head sourceAlert on lag and show freshness to usersAlert
04block.hash on every checkLog it with the block number for support requestsRecord

Run the same _meta query on a schedule and act on each signal. Check indexing errors first, then the serving deployment, then freshness.

Compare _meta.block.number with the chain head only when you have a reliable head source for the same network. If _meta.hasIndexingErrors is true, follow the checks in Troubleshooting.

Recent blocks can still be corrected by a chain reorganization. See Sync and reorgs before you treat a result as final.

Prerequisites

Request

Response

Act on each signal

Next steps