Skip to main content

Subgraph Monitor

Watch indexing lag, health, and latency for the subgraphs your app depends on before stale data reaches users.

Why teams use this monitor

A subgraph can be “online” and still be dangerous if it is behind enough blocks that your frontend or automation sees stale state.

  • Frontend teams depending on The Graph for app state
  • Analytics teams consuming indexed data pipelines
  • Teams that already know which subgraph is production-critical

Quick start in 5 minutes

  1. Start with the one subgraph your main user flow depends on.
  2. Choose a blocks-behind threshold based on how stale data becomes user-visible, not an arbitrary round number.
  3. Only set a custom graphStatusUrl if you already operate a private or custom status endpoint.

Configuration notes

FieldWhat to know
subgraphNameThis is the display name. Use something your on-call team will recognize instantly.
subgraphIdLeave this empty if you do not already know the exact deployment hash.
maxBlocksBehind / criticalBlocksBehindThese are your stale-data guardrails. Tie them to real product tolerance.
maxLatencyMsUse this for query-performance degradation, especially if a synced subgraph still feels slow to users.

Recommended thresholds and defaults

  • Critical product paths often start around 20-50 warning blocks and 200-500 critical blocks.
  • Analytics-only subgraphs can usually tolerate more lag than interactive user flows.
  • Latency thresholds matter most when your app depends on query speed as much as indexing freshness.

Ready-made examples

Frontend dependency subgraph

Use tighter lag thresholds when user flows depend on freshness.

Setup time: 3 min

Best for

Interactive apps with token balances, positions, or pool state in the UI

  • Ethereum mainnet
  • Warning at 40 blocks
  • Latency cap at 2500ms
{
  "name": "Frontend dependency subgraph",
  "subgraphName": "Uniswap V3 Mainnet",
  "subgraphId": "",
  "network": "mainnet",
  "graphStatusUrl": "https://api.thegraph.com/index-node/graphql",
  "maxBlocksBehind": 40,
  "criticalBlocksBehind": 250,
  "maxLatencyMs": 2500,
  "checkIntervalSeconds": 60
}

Analytics subgraph

A more tolerant profile for BI and reporting workloads.

Setup time: 3 min

Best for

Dashboards and internal analytics pipelines

  • Arbitrum One
  • Warning at 150 blocks
  • 5 min checks
{
  "name": "Analytics subgraph",
  "subgraphName": "GMX Analytics",
  "subgraphId": "",
  "network": "arbitrum-one",
  "graphStatusUrl": "https://api.thegraph.com/index-node/graphql",
  "maxBlocksBehind": 150,
  "criticalBlocksBehind": 1000,
  "maxLatencyMs": 5000,
  "checkIntervalSeconds": 300
}

Critical protocol subgraph

Use a tighter profile for protocol or automation dependencies.

Setup time: 3 min

Best for

Keepers, bots, or protocol-critical indexing dependencies

  • Base network
  • Warning at 25 blocks
  • Critical at 120 blocks
{
  "name": "Critical protocol subgraph",
  "subgraphName": "Base protocol sync",
  "subgraphId": "",
  "network": "base",
  "graphStatusUrl": "https://api.thegraph.com/index-node/graphql",
  "maxBlocksBehind": 25,
  "criticalBlocksBehind": 120,
  "maxLatencyMs": 2000,
  "checkIntervalSeconds": 60
}

Alert example

Subgraph lag warning

Subgraph alert: indexing lag exceeded your warning threshold.
Current lag: 84 blocks
Warning threshold: 40 blocks
Suggested action: treat frontend or automation data as stale until the subgraph catches up.

Troubleshooting

The monitor shows healthy but the app still feels stale.

Lower maxBlocksBehind or add a tighter latency threshold for that user path.

The monitor is always critical during chain spikes.

Your product tolerance may be higher than the current threshold. Align it to real operational impact.

The status URL works manually but the monitor stays unknown.

Verify the URL is the Graph status endpoint, not a regular query endpoint.

Next steps