Subgraphs: Manage Endpoint Aliases

Keep the same query URL when you release a new Subgraph version. An Endpoint Alias gives your application a name such as positions or production, while your organization chooses its target and when that target changes.

Prerequisites

A GraphOps organization with Subgraphs access.
An Owner or Developer role to manage Endpoint Aliases.
A Subgraphs API key.
A Deployment CID, Graph Network Subgraph ID, or existing Managed Subgraph to target.
The schema fields your production clients use, so you can check compatibility before you retarget.

Choose a target type

The Target type decides when your Endpoint Alias moves to a new deployment:

Deployment CID: stays on that exact deployment until you change it.
Graph Network Subgraph ID: follows the latest validated publication for that ID automatically, including schema changes chosen by the Subgraph owner. It can move before a Managed Subgraph finishes indexing the same publication.
Managed Subgraph: follows the Managed Subgraph's serving Current version, so it moves only after a Next version meets the readiness checks and is promoted.

01BeforeAll three Endpoint Aliases serve the owner's published version.Graph Network Subgraph IDQm…a1f4Managed SubgraphQm…a1f4Deployment CIDQm…a1f4
02Owner publishesThe Graph Network Subgraph ID target moves once the release is validated. The Managed Subgraph indexes it as Next.Graph Network Subgraph IDQm…7c2eManaged SubgraphQm…a1f4Next SyncingDeployment CIDQm…a1f4
03Next is promotedThe Managed Subgraph target moves after its Next version is ready. The Deployment CID target stays until you change it.Graph Network Subgraph IDQm…7c2eManaged SubgraphQm…7c2eDeployment CIDQm…a1f4

Three Endpoint Aliases, one per Target type, when the owner publishes a new version and the Managed Subgraph follows the same Graph Network Subgraph ID. Each moves at a different time.

Choose a Managed Subgraph target when indexing readiness should control endpoint changes. Choose a Deployment CID target when your team wants to change deployments by hand.

Choose and update an Endpoint Alias

Create or choose the Endpoint Alias

Choose a short name that represents the application contract, such as uniswap-v3, positions, or production.

Endpoint Alias query URL:

https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

Point the Endpoint Alias to a target

Open Subgraphs and create or update an Endpoint Alias. Choose its Target type, then enter a Deployment CID or Graph Network Subgraph ID, or select a Managed Subgraph.

Every target must resolve to a valid single-network deployment. If a Graph Network Subgraph ID target can't be resolved later, the Endpoint Alias keeps its last mapping and shows a tracking error.

Verify the target

The Target type column shows how each Endpoint Alias follows its target; its info icon explains that type. The Target column shows the Graph Network Subgraph ID or Managed Subgraph the Endpoint Alias follows and the Serving Deployment CID. Use the row's actions to explore the target's schema or get its query endpoint.

Then query _meta through the Endpoint Alias:

query AliasTarget {
  _meta {
    deployment
    block {
      number
      hash
    }
    hasIndexingErrors
  }
}

{  "data": {    "_meta": {      "deployment": "Qm...",Should match the Serving Deployment CID      "block": {        "number": 18000000,Should keep rising on the new target        "hash": "0x..."      },      "hasIndexingErrors": falseRoll back if this turns true    }  }}

An illustrative check after an Endpoint Alias update. The deployment should match the Serving Deployment CID shown for the Endpoint Alias.

Roll back if needed

For an Endpoint Alias with a Deployment CID target, change its target to the previous Deployment CID after confirming that deployment is queryable. Keep previous CIDs in your release records.

For an Endpoint Alias with a Managed Subgraph target, prepare and promote the previous deployment as another Managed Subgraph upgrade, or explicitly convert the Endpoint Alias to a Deployment CID target. A Managed Subgraph upgrade must meet the readiness checks before promotion. To stop an Endpoint Alias from following Graph Network publications, convert it to a Deployment CID target.

Release safely

Treat Endpoint Alias updates as application releases, and retarget during low-risk windows if schema changes can affect live traffic.
Confirm required entity names, fields, filters, and ordering fields before you retarget.
Keep previous Deployment CIDs available as rollback targets.
Log _meta.deployment in production diagnostics so support can see which deployment served a request.