How do I see the query plan for a federated query?

Add the X-WG-Include-Query-Plan header to your request in the playground. The plan appears in the extensions field of the response.

Can I inspect the plan without generating subgraph traffic?

Yes. Add X-WG-Skip-Loader alongside X-WG-Include-Query-Plan. The router returns the plan but skips subgraph requests. Data in the response returns as null.

What does the query plan contain?

The plan describes the fetch operations the router will execute, their dependencies, and which subgraphs they target.

What does X-WG-Disable-Tracing do?

It excludes the request from router tracing, so plan inspection requests do not generate trace data.

Is the query plan feature available in all environments?

The feature is available wherever the Cosmo Router is deployed. No additional router configuration is required.

Where is the query plan visible in the response?

The plan is returned in the extensions field of the GraphQL response, alongside the data and any errors.

Query Plan Visualization for Federated GraphQL | Cosmo by WunderGraph

The problem

Federation routing is invisible by default

The router plans and executes subgraph calls internally. Without exposing that plan, you cannot see the routing logic, identify extra fetches, or verify execution order.

Query routing is a black box

The router decides which subgraphs to call and in what order. Without visibility into that decision, debugging unexpected routing or fetch behavior requires guesswork.

Performance problems are hard to diagnose without plan data

A query making more subgraph calls than expected, or fetching sequentially when parallel execution is possible, is invisible without the plan.

Testing the plan requires generating actual traffic

There is no way to inspect the routing logic without running the full query and observing subgraph calls — until the plan is exposed directly.

Our solution

The execution plan in the response extensions

Add a single header and the Cosmo Router returns the full query plan alongside your response. The plan shows every fetch operation, its dependencies, and the subgraphs it targets — visible directly in the playground.

From header to plan

Include the X-WG-Include-Query-Plan header in a playground request.
The Cosmo Router processes the query and generates a query plan.
The plan is returned in the extensions field of the response alongside the data.
The plan describes fetch operations, their dependencies, and which subgraphs they target.
To inspect the plan without making subgraph requests, add X-WG-Skip-Loader. Data in the response returns as null, but the plan is complete.
Add X-WG-Disable-Tracing to prevent the plan request from generating trace data in the router.

One header. Full execution plan. No guesswork.

Query Plan Visualization

Before & After

Before Cosmo	With Cosmo
Query routing is opaque	Full execution plan in the response extensions
No insight into fetch strategy before running	See subgraph calls and dependencies before execution
Generating traffic required to understand routing	X-WG-Skip-Loader skips subgraph requests for plan-only analysis
Debugging routing inefficiencies requires trial and error	Identify extra fetches and dependencies directly from the plan

Headers

Header reference

X-WG-Include-Query-Plan: Returns the query plan in the response extensions field.
X-WG-Skip-Loader: Skips subgraph requests. Data returns as null. Use for plan-only analysis.
X-WG-Disable-Tracing: Excludes the request from router tracing.

How query plan visualization works

01

Header activates plan output.

Add header

Include X-WG-Include-Query-Plan in the playground request headers. No router configuration is required.

02

Plan in extensions field.

Receive plan

The router returns the query plan in the response extensions field alongside the query data.

03

Fetch order and dependencies visible.

Inspect

Read the plan to see which subgraphs will be called, in what order, and what data dependencies exist between fetch operations.

04

Zero production impact plan analysis.

Skip loader

Add X-WG-Skip-Loader to get the plan without making subgraph requests. Data returns as null. Use this to analyze plans with zero production impact.

Capabilities

What you get with Query Plan Visualization

Plan in extensions

The query plan appears in the extensions field of the response. Inspect it directly in the playground response panel.

Skip-loader mode

Combine X-WG-Include-Query-Plan and X-WG-Skip-Loader to analyze the full plan without making any subgraph requests.

Fetch order and dependencies

The plan shows which subgraphs are called, in what sequence, and what data dependencies exist between fetch operations.

Playground integration

View the plan directly in the Cosmo Studio playground without any external tooling.

See exactly how your query executes

Add X-WG-Include-Query-Plan to any playground request. The full execution plan appears in the response extensions.

Start Free Read the Docs

See the router's query plan before your request reaches a subgraph