EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
Stream Live Data Through GraphOS
GraphQL subscriptions in a federated supergraph with Apollo Client
Choose this path when your product needs live updates in the browser and your API is already (or will be) a federated supergraph in Apollo GraphOS. Clients use GraphQL subscriptions against the GraphOS Router over HTTP, including the multipart subscription protocol. The router keeps the long-lived subscription open to the subgraph that owns the subscription field, usually over WebSocket or an HTTP callback, while Apollo Client on the web talks only to the router.
Read how subscription traffic flows in a supergraph in the router documentation for a full picture before you implement.
Prerequisites
A supergraph registered in Apollo GraphOS and a running GraphOS Router that clients can reach
At least one subgraph you control where you can add a
Subscriptiontype and resolvers (for example Apollo Server with@apollo/subgraph)A React web app where you can configure Apollo Client
By the end of this guide, you'll have:
A subscription field defined on the owning subgraph and included in your published supergraph schema
Router configuration that enables subscriptions and reaches your subgraph subscription endpoint
Apollo Client pointed at the router HTTP endpoint with subscriptions over HTTP enabled
A React component that uses
useSubscriptionagainst the supergraph operation
Steps to complete
1. Implement the subscription on the owning subgraph
Define the subscription in the subgraph schema that originates the event stream (the subgraph that resolves the root subscription field). Implement resolvers with an async iterator the same way you do for a standalone server, and expose a GraphQL endpoint the router can use for subgraph operations.
Follow Subscriptions in Apollo Server for schema and resolver patterns. Follow Federation subgraph basics to keep types and directives aligned with your supergraph.
If the subscription returns entity types that other subgraphs extend, the router resolves those pieces with follow-up queries across subgraphs; you still declare the subscription only on the subgraph that owns the root subscription field.
2. Enable subscriptions on the GraphOS Router
Configure your router so it accepts subscription operations from clients and can open a subscription to the correct subgraph. You typically set:
Subscription support enabled for the router
Per-subgraph WebSocket (or callback) URLs and protocols so the router matches what the subgraph exposes
Work through GraphQL subscriptions with the GraphOS Router, including subgraph protocol details, before you test from a client.
3. Publish the subgraph schema to GraphOS
Publish the updated subgraph schema (with the new subscription definitions) using your usual workflow (Rover or CI). Confirm in GraphOS Studio that the supergraph schema lists your subscription fields at the root Subscription type.
If composition fails, fix schema ownership and federation directives before you move on.
4. Configure Apollo Client for HTTP subscriptions to the router
Use your router’s GraphQL URL as the single endpoint for queries, mutations, and subscriptions. Enable HTTP-based (multipart) subscriptions in Apollo Client so subscription operations use the same origin as the rest of your traffic—no separate WebSocket link to the router.
Follow the HTTP section in Subscriptions in Apollo Client (React) and point the client at the router endpoint GraphOS gives you.
5. Subscribe from React
Define the subscription with gql, run it with useSubscription, and render data as it arrives. The hook behavior matches other Apollo Client usage; the transport underneath is multipart HTTP to the router.
Related guides
Set up your Clients for caching, authentication, and production client practices
Deploy router in test if you still need a non-production router endpoint