How Do You Run a Sui GraphQL Introspection Query?

Sui exposes a GraphQL interface that sits alongside its gRPC and JSON-RPC APIs. GraphQL gives you a typed schema, so instead of memorizing method names you can ask the endpoint what it supports. That is exactly what an introspection query does: it returns the schema itself, including types, fields, arguments, and descriptions.

This tutorial walks through sending an introspection query to a Sui GraphQL endpoint, reading the response, and turning that schema into working queries. It also covers the practical question developers hit next: should you point introspection and app traffic at a shared endpoint, or move to dedicated infrastructure?

When introspection is the right move (and when it is not)

Introspection is a development and tooling feature, not a production data path. Use it when you are exploring the schema, generating typed clients, or validating that a field still exists after a network upgrade.

If you are still deciding between Sui's interfaces, the Sui API overview is a good starting point before you commit to GraphQL.

Sui GraphQL endpoint basics

A Sui GraphQL endpoint accepts HTTP POST requests with a JSON body containing a query string and optional variables. The endpoint is a single URL; you select the data shape through the query itself rather than through different paths.

Before you send an introspection query, confirm three things:

1. The endpoint URL you are targeting (mainnet or testnet).
2. That the endpoint accepts application/json POST bodies.
3. Whether the endpoint restricts introspection in production.

Some managed providers disable introspection on shared endpoints to reduce load, while dedicated nodes usually leave it enabled. If introspection returns an error about being disabled, that is a configuration choice, not a bug in your query.

Sending your first introspection query

The standard introspection query is verbose because it walks the full type system. Start with a smaller query that lists the root query fields, then expand once you confirm the endpoint responds.

curl -s https://your-sui-graphql-endpoint.example/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ __schema { queryType { name } types { name kind } } }"
  }'

Replace the placeholder URL with the GraphQL endpoint from your provider. The response contains a data.__schema object. queryType.name tells you the name of the root query type, and types lists every type in the schema with its kind (OBJECT, SCALAR, ENUM, INPUT_OBJECT, and so on).

If you get a data object back, the endpoint is working. If you get an errors array, read the message carefully; it usually tells you whether the problem is authentication, a disabled feature, or a malformed query.

Reading the schema response

The full introspection result is large. Rather than dumping it to the terminal, pipe it to a file and query it locally.

curl -s https://your-sui-graphql-endpoint.example/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  > sui-schema.json

Now you can inspect it with jq:

jq '.data.__schema.types[] | select(.name == "Query") | .fields[].name' sui-schema.json

That command lists the top-level fields available on the root query type. From there you can drill into any type to see its fields and arguments. This is the fastest way to answer questions like "what is the exact field name for a transaction digest" without reading external docs.

Turning the schema into a working query

Once you know the field names, build a small query and test it. A typical pattern is to fetch a single object by an identifier and select only the fields you need.

const query = `
  query GetObject($id: SuiAddress!) {
    object(address: $id) {
      address
      version
      digest
    }
  }
`;

const res = await fetch("https://your-sui-graphql-endpoint.example/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query, variables: { id: "0x..." } })
});

const json = await res.json();
console.log(json.data);

The exact field names and argument types come from your introspection result, so treat the snippet above as a shape rather than a copy-paste guarantee. If a field name differs on your endpoint, the schema is the source of truth.

Introspection in CI: catching schema drift

Sui's schema evolves. Fields get added, deprecated, or renamed. If your app depends on a field that disappears, you find out in production unless you check earlier.

A practical pattern is to store a snapshot of the introspection result and compare it on every deploy:

# Save a baseline once
curl -s $SUI_GRAPHQL_ENDPOINT -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  > schema-baseline.json

# In CI, fetch the current schema and diff
curl -s $SUI_GRAPHQL_ENDPOINT -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  > schema-current.json

diff <(jq -S . schema-baseline.json) <(jq -S . schema-current.json)

A non-empty diff is not automatically a failure, but it is a signal to review whether your queries still match the schema. This is especially useful before a network upgrade.

Common introspection errors and what they mean

If you repeatedly hit timeouts on the full introspection query, request only the types you care about. Introspection supports filtering by walking specific types rather than the whole schema.

Choosing an endpoint for introspection and app traffic

Introspection is cheap to run occasionally but expensive if you hammer it. The endpoint you use for schema exploration does not have to be the same one your app uses for production reads.

A common split looks like this:

• Development and CI: a managed endpoint that allows introspection, used for codegen and schema diffs.
• Production reads: a dedicated node with fixed queries, predictable capacity, and no introspection overhead.

OnFinality provides both RPC API access and dedicated node infrastructure for Sui. If you want to understand how to weigh shared versus dedicated endpoints, the guide on choosing an RPC provider covers the tradeoffs, and RPC pricing shows how plans are structured. You can also review supported RPC networks to see where Sui fits in the wider lineup.

Key Takeaways

• A Sui GraphQL introspection query returns the schema, letting you discover types and fields at runtime.
• Start with a narrow introspection query, then expand once the endpoint responds.
• Pipe large responses to a file and inspect them with jq instead of reading raw JSON.
• Some shared endpoints disable introspection; dedicated nodes typically allow it.
• Store a schema snapshot and diff it in CI to catch schema drift before it breaks production.
• Separate your schema-exploration endpoint from your production read path.

FAQ

Does Sui GraphQL support the standard introspection query? Yes, Sui's GraphQL interface follows the GraphQL specification, so __schema and __type introspection fields work where the endpoint allows introspection.

Why does introspection return an error on my endpoint? The most common reason is that the provider disables introspection on shared endpoints to reduce load. Check your provider's documentation or move to a dedicated node.

Can I use introspection to generate a typed client? Yes. Save the introspection result and feed it to a GraphQL code generator to produce typed queries for your language.

Is introspection safe to run in production? It is safe to run occasionally, but it is not a data path. Keep it in development and CI, and use fixed queries for production traffic.

How often does the Sui GraphQL schema change? The schema evolves with network upgrades. Diffing a stored snapshot in CI is the simplest way to stay aware of changes.

Do I need a dedicated node to use GraphQL? No, but a dedicated node gives you consistent access and avoids shared-endpoint restrictions such as disabled introspection. See Sui RPC for endpoint options.