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:

Reference

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:

Reference

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.

JSON

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

Output

{  "data": {Present when the query ran    "pools": [      {        "id": "0x000024feb293b6c6c3a80a95f1f830a8746400b9"No matching entities, not an error      },      {        "id": "0x0000d36ab86d213c14d93cd5ae78615a20596505"      },      {        "id": "0x00013bffe4c38c1372a450fac78b01cb4f554781"      },      {        "id": "0x0001fcbba8eb491c3ccfeddc5a5caba1a98c4c28"      },      {        "id": "0x00024b66a38a676c0eae59126c1367ad141afa79"      }    ]  }}

Request

These clients send the request envelope above through an Endpoint Alias.

Prerequisites

Set GRAPHOPS_API_KEY to your GraphOps API key.
Replace <ALIAS> with your Endpoint Alias.

curl

Example project

curl --fail-with-body --silent --show-error "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"
  }'

Output

{  "data": {Present when the query ran    "pools": [      {        "id": "0x000024feb293b6c6c3a80a95f1f830a8746400b9",No matching entities, not an error        "token0": {          "symbol": "TRUMP"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x0000d36ab86d213c14d93cd5ae78615a20596505",        "token0": {          "symbol": "RALPH"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x00013bffe4c38c1372a450fac78b01cb4f554781",        "token0": {          "symbol": "Pectra"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x0001fcbba8eb491c3ccfeddc5a5caba1a98c4c28",        "token0": {          "symbol": "BCZ"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x00024b66a38a676c0eae59126c1367ad141afa79",        "token0": {          "symbol": "WETH"        },        "token1": {          "symbol": "TI"        }      }    ],    "_meta": {      "block": {        "number": 26250895,Indexed block behind the result        "hash": "0x03743f151dadd179f2b80bdcd3da79ea06388df99c013e606372303ce6c865d6"      }    }  }}

Response

Successful GraphQL responses include data. An empty list is a valid result when no entities match:

JSON

{
  "query": "query EmptyPools { pools(first: 10, where: { id_gt: \"0xffffffffffffffffffffffffffffffffffffffff\" }, orderBy: id) { id } _meta { block { number } } }"
}

Output

{  "data": {    "pools": [],A successful query with no matching pools    "_meta": {      "block": {        "number": 26250903Historical block served: 26,250,903      }    }  }}

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

JSON

{
  "query": "query InvalidField { notARealField }"
}

Output

{  "errors": [Can arrive with HTTP 200    {      "message": "Cannot query field \"notARealField\" on type \"Query\".",Fix the query; retrying will not help      "locations": [        {          "line": 1,          "column": 22        }      ]    }  ]}

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

Endpoint patterns

Endpoint preview

Request envelope

Request

Response

Error responses

Next steps