Subgraphs: API integration

Use this reference to build Subgraph requests and interpret their responses. GraphOps Subgraphs exposes standard GraphQL query endpoints over HTTPS. Each endpoint is selected by Deployment CID, Graph Network Subgraph ID, or GraphOps Endpoint Alias, and authenticated with a Subgraphs API key.

Endpoint patterns

Header-authenticated endpoints:

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>
https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

A Subgraphs endpoint names what to query in its path: the identifier type, then the identifier. This example uses an Endpoint Alias; deploymentCID and subgraphId work the same way. Send the API key in the Authorization header or append it to the path.

Route-token endpoints:

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>/<GRAPHOPS_API_KEY>
https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>/<GRAPHOPS_API_KEY>
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>/<GRAPHOPS_API_KEY>

Endpoint preview

Endpoint type

Use a Qm… Deployment CID for one version.

Authorization

Query endpoint

Replace placeholders with your identifier and API key before making requests.

Request header

Get query endpoint

See Authentication to choose how to send your API key and protect it in logs.

Request envelope

Subgraph queries use the standard GraphQL HTTP request shape:

Field	Type	Required	Notes
`query`	string	Yes	GraphQL query or mutation text. Query support depends on the Subgraph schema.
`variables`	object	No	Variables referenced by the query.
`operationName`	string	No	Required only when the document contains multiple named operations.

{
  "query": "query Pools($first: Int!) { pools(first: $first) { id } }",
  "variables": {
    "first": 5
  },
  "operationName": "Pools"
}

Request

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

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 Pools($first: Int!) {
          pools(first: $first) {
            id
            token0 { symbol }
            token1 { symbol }
          }
          _meta { block { number hash } }
        }
      `,
      variables: { first: 5 },
      operationName: "Pools",
    }),
  },
);

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

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 Pools($first: Int!) {
    pools(first: $first) {
      id
      token0 { symbol }
      token1 { symbol }
    }
    _meta { block { number hash } }
  }
`;

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

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 Pools($first: Int!) {
          pools(first: $first) {
            id
            token0 { symbol }
            token1 { symbol }
          }
          _meta { block { number hash } }
        }
        """,
        "variables": {"first": 5},
        "operationName": "Pools",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"]["pools"])

Response

Successful GraphQL responses include data:

{  "data": {Present when the query ran    "pools": [],No matching entities, not an error    "_meta": {      "block": {        "number": 18000000,Indexed block behind the result        "hash": "0x..."      }    }  }}

An illustrative success: data holds one field per top-level selection, and an empty list is a valid result.

Responses can include errors even when the HTTP request succeeds. Check for errors on every response:

{  "errors": [Can arrive with HTTP 200    {      "message": "Cannot query field \"poolz\" on type \"Query\"."Fix the query; retrying will not help    }  ]}

A validation error can arrive with HTTP status 200. Check every response for an errors array before you read data.

Error responses

Code or status	Meaning	Typical response
`400`	Invalid HTTP request, invalid JSON, or malformed GraphQL document.	Fix request encoding or query syntax.
`401`	Missing or invalid API key.	Check Authentication.
`403`	Organization is not entitled to the endpoint, Endpoint Alias, or feature.	Check organization access and plan.
`404`	Deployment CID, Graph Network Subgraph ID, or Endpoint Alias was not found.	Confirm the identifier in the platform UI.
`413`	Request or response is too large.	Reduce query selection or page size.
`429`	Organization exceeded query rate limits.	Back off and reduce request rate.
`5xx`	Gateway or upstream indexing service failure.	Retry if transient; contact support if persistent.
GraphQL `errors`	Schema, validation, resolver, or indexing issue.	Inspect the error message and `_meta`.