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

Add `X-WG-Include-Query-Plan` and receive the full execution plan in the response extensions. Inspect subgraph routing and dependencies without guesswork.

No router configuration required. Add the header and the plan appears in the response.

---

## 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

1. Include the X-WG-Include-Query-Plan header in a playground request.
2. The Cosmo Router processes the query and generates a query plan.
3. The plan is returned in the extensions field of the response alongside the data.
4. The plan describes fetch operations, their dependencies, and which subgraphs they target.
5. 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.
6. Add X-WG-Disable-Tracing to prevent the plan request from generating trace data in the router.

---

## 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 |

---

### 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

1. **Add header**: Include X-WG-Include-Query-Plan in the playground request headers. No router configuration is required.
2. **Plan in extensions field**: The router returns the query plan in the response extensions field alongside the query data.
3. **Fetch order and dependencies visible**: Read the plan to see which subgraphs will be called, in what order, and what data dependencies exist between fetch operations.
4. **Zero production impact plan analysis**: 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.