GraphQL

Shape one request across the registry — a subnet with health, surfaces, endpoints, and economics, a provider with its subnets, or the economic opportunity boards. No API key.

Endpoint

POST a GraphQL document. GET returns the published SDL. Introspection is enabled. Mainnet-only path.

POST · GET

https://api.metagraph.sh/api/v1/graphql

Example

curl -X POST https://api.metagraph.sh/api/v1/graphql \
  -H 'content-type: application/json' \
  -d '{"query":"{ subnet(netuid: 7) { name health { status } surfaces { kind url } economics { emission_share } } }"}'

Schema

GET the endpoint for the live SDL. Introspection queries (__schema / __type) are allowed and exempt from the depth and complexity budgets applied to product queries.

GET /api/v1/graphql → SDL document
POST /api/v1/graphql → { "query", "variables?", "operationName?" }
Field names mirror artifact JSON keys (snake_case) so resolvers read registry rows directly.

Root queries

Ten Query roots cover the same registry surfaces as REST. List roots take cursor pagination; relationship fields (fresh nested artifacts) cost more against the complexity budget.

Field	Args	Returns	Summary
subnets	limit, cursor	SubnetList!	Paginated active-subnet index.
subnet	netuid!	Subnet	One subnet with health, surfaces, endpoints, and economics.
providers	limit, cursor	ProviderList!	Paginated provider/source registry.
provider	id!	Provider	One provider with its subnets.
economics	limit, cursor	EconomicsList!	Paginated per-subnet economic + validator metrics.
surfaces	netuid, limit, cursor	SurfaceList!	Curated public surfaces, optionally scoped to one subnet.
endpoints	netuid, limit, cursor	EndpointList!	Endpoint/resource registry, optionally scoped to one subnet.
health	—	GlobalHealth	Global operational health rollup with per-subnet summaries.
opportunity_boards	limit	OpportunityBoards!	Cross-subnet economic opportunity boards.
compare	netuids!, dimensions	Compare!	Side-by-side registry / economics / health for requested netuids.

Subscriptions: chainEvents over the same path via graphql-transport-ws (WebSocket). See For agents for other machine surfaces.

Limits

Hard caps enforced on every POST. Matching constants live in src/graphql.mjs; rate limiting is keyed per client IP alongside the RPC proxy.

Limit	Value	Notes
Max depth	7	Nested selection sets beyond this fail validation.
Max complexity	50	Default field cost 1; relationship roots cost 5.
Max POST body	64 KiB	HTTP request body size cap for POST /api/v1/graphql.
Max query document	16 KiB	Raw query string / document length cap.
Page size	20 default · 100 max	Cursor pagination on list roots (subnets, providers, …).
Rate limit	100 / 60s	Per-client IP, shared policy with the RPC proxy (429 + retry-after).