GraphQL

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

GraphQL isn't part of the typed @jsonbored/metagraphed / metagraphed SDKs — they're built around the REST envelope. Plain HTTP works with any client:

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 } } }"}'

Explorer

Open the GraphQL Explorer

Interactive GraphiQL IDE, full height, on its own page — schema-aware autocomplete, docs, and history against the live endpoint.

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).