Subgraphs: Query a Subgraph

Read indexed entities from your application and know how fresh they are. This guide sends a parameterized GraphQL query through an Endpoint Alias, includes _meta so each response reports the indexed block behind it, and checks for GraphQL errors that can arrive with HTTP 200.

The example requires pools, token0, token1, and totalValueLockedUSD fields from a Uniswap-style schema. If your Subgraph uses a different schema, adapt the selection using Schema reference. The same request works with a Deployment CID or Graph Network Subgraph ID endpoint.

Prerequisites

A Subgraphs API key from the GraphOps Platform UI.
A Deployment CID, Graph Network Subgraph ID, or Endpoint Alias for the Subgraph you want to query.
The GraphQL schema for that Subgraph, or introspection access to discover it.

Request

This request reads the five pools with the highest total value locked and returns Subgraph metadata.

curl "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>" \
  -H "Authorization: Bearer <GRAPHOPS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query TopPools($first: Int!) { pools(first: $first, orderBy: totalValueLockedUSD, orderDirection: desc) { id token0 { symbol } token1 { symbol } totalValueLockedUSD } _meta { block { number hash } hasIndexingErrors } }",
    "variables": { "first": 5 },
    "operationName": "TopPools"
  }'

const response = await fetch(
  "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <GRAPHOPS_API_KEY>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        query TopPools($first: Int!) {
          pools(
            first: $first
            orderBy: totalValueLockedUSD
            orderDirection: desc
          ) {
            id
            token0 { symbol }
            token1 { symbol }
            totalValueLockedUSD
          }
          _meta {
            block { number hash }
            hasIndexingErrors
          }
        }
      `,
      variables: { first: 5 },
      operationName: "TopPools",
    }),
  },
);

const result = await response.json();
console.log(result.data.pools);
console.log(result.data._meta.block.number);

import { GraphQLClient, gql } from "graphql-request";

const client = new GraphQLClient(
  "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>",
  {
    headers: {
      Authorization: "Bearer <GRAPHOPS_API_KEY>",
    },
  },
);

const query = gql`
  query TopPools($first: Int!) {
    pools(
      first: $first
      orderBy: totalValueLockedUSD
      orderDirection: desc
    ) {
      id
      token0 { symbol }
      token1 { symbol }
      totalValueLockedUSD
    }
    _meta {
      block { number hash }
      hasIndexingErrors
    }
  }
`;

const result = await client.request(query, { first: 5 });
console.log(result.pools);
console.log(result._meta.block.number);

import requests

response = requests.post(
    "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>",
    headers={
        "Authorization": "Bearer <GRAPHOPS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "query": """
        query TopPools($first: Int!) {
          pools(
            first: $first
            orderBy: totalValueLockedUSD
            orderDirection: desc
          ) {
            id
            token0 { symbol }
            token1 { symbol }
            totalValueLockedUSD
          }
          _meta {
            block { number hash }
            hasIndexingErrors
          }
        }
        """,
        "variables": {"first": 5},
        "operationName": "TopPools",
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()
print(result["data"]["pools"])
print(result["data"]["_meta"]["block"]["number"])

Response

{  "data": {    "pools": [Up to $first pools, largest first      {        "id": "0x...",        "token0": { "symbol": "USDC" },        "token1": { "symbol": "WETH" },        "totalValueLockedUSD": "123456789.123"BigDecimal values arrive as strings      }    ],    "_meta": {      "block": {        "number": 18000000,The data reflects this block        "hash": "0x..."      },      "hasIndexingErrors": falseTreat true as a data-quality warning    }  }}

An illustrative page of results. Read data only when the response has no errors array, then use _meta to judge how fresh it is.

Handle the result

Check for an errors array before you read data. GraphQL errors can arrive with HTTP 200, and a response can contain both data and errors.
Treat an empty list as a valid result, not a failure.
Read _meta.block.number when you display or store the data, and alert when _meta.hasIndexingErrors is true.
Request only the fields your application renders or stores, and page through larger collections.

Use Endpoint Aliases for application endpoints when your team needs controlled upgrades. Use Deployment CIDs for tests and rollback targets that must stay on one immutable deployment.

Prerequisites

Request

Response

Handle the result

Next steps