Querying a Subgraph

The HTTP endpoint for GraphQL queries can be found on the subgraph page in the dashboard.

Authentication and API restrictions

Query keys

All GraphQL queries are authenticated using a query key. Your organization can have multiple query keys with the following settings:

• Origins: Permitted origins for queries. Wildcard matching is supported (e.g. *.satsuma.xyz).

• Rate limits (Coming soon): Queries per second allowed per query key.

Example use cases:

• From your backend - Create a query key with no origin restrictions and no rate limit.

• From your frontend - Create a query key that allows origins from your domain(s) and has no rate limit.

• For your community - Create a query key with a rate limit and no origin restrictions.

Using query keys

We currently support two ways of passing in query keys into queries — by path and by header.

Path

The query key can be included as part of the URL path. For example:

curl -v \
	'https://subgraph.satsuma-prod.com/<QUERY_KEY>/<ORGANIZATION>/<SUBGRAPH_NAME>/version/<VERSION_NAME>/api' \
  --data-raw '{"query":"{entities(first:1){id}}"}'

Header

The query key can be attached with a x-api-key header. For example:

curl -v \
	'https://subgraph.satsuma-prod.com/<ORGANIZATION>/<SUBGRAPH_NAME>/version/<VERSION_NAME>/api' \
  -H 'x-api-key: <QUERY_KEY>' \
  --data-raw '{"query":"{entities(first:1){id}}"}'

Rate Limits

GraphQL queries are subject to rate limits set on each organization.

Throttled requests will receive a 429 response and all responses will contain rate limit related headers.

Please check the billing dashboard to see rate limit details for your organization.

Indexing Status

We provide an indexing status endpoint for each subgraph version, including the live version. You can find the indexing status endpoint on the subgraph page. It returns the following information:

{
  "data": {
    "indexingStatusForCurrentVersion": {
      "subgraph": "QmXqNgptc2b5WzwmFfCu8PxsLgetBe5M8eBKvSyu5jqkei",
      "synced": true,
      "health": "healthy",
      "fatalError": null,
      "nonFatalErrors": [],
      "chains": [
        {
          "chainHeadBlock": {
            "number": "17787217"
          },
          "latestBlock": {
            "number": "17787217"
          }
        }
      ]
    }
  }
}

entityChangesInBlock

We now also expose the entityChangesInBlock field from the indexing status endpoint:

$INDEXING_STATUS_ENDPOINT/entityChangesInBlock?blockNumber=123456

If your subgraph has immutable entities, you will receive the following error:

{
  "errors": [
    {
      "message": "Store error: store error: column \"block_range\" does not exist"
    }
  ]
}

Other Fields

If your team needs more fields from the graph-node indexing status endpoint, please let us know!