Install & Compatibility
Where this runs
tested against v1.13.20 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 3.592s · 144.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 15.2s · import 3.400s · 141MB
148MB installed
● package 148MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DagsterGraphQLClient
✓ from dagster_graphql import DagsterGraphQLClient
This is the primary client for programmatic interaction with the Dagster GraphQL API.
This quickstart demonstrates how to initialize the `DagsterGraphQLClient` and execute a raw GraphQL query to fetch recent Dagster runs. For Dagster Cloud, you would configure the client with your deployment URL and a user token. Ensure a Dagster instance (e.g., via `dagster dev`) is running and accessible at the specified host and port for the local example.
import os
from dagster_graphql import DagsterGraphQLClient
# Configure client for local Dagster instance or Dagster Cloud
# For local: DagsterGraphQLClient("localhost", port_number=3000)
# For Dagster Cloud:
# url = os.environ.get("DAGSTER_CLOUD_URL", "YOUR_ORG.dagster.cloud/prod")
# token = os.environ.get("DAGSTER_CLOUD_API_TOKEN", "YOUR_TOKEN")
# Example for a local Dagster instance (run 'dagster dev' first)
client = DagsterGraphQLClient("localhost", port_number=3000)
try:
# Example: Get a list of recent runs
runs_query = """
query LatestRuns {
runsOrError {
__typename
... on Runs {
results {
id
status
pipelineName
}
}
... on PythonError {
message
}
}
}
"""
result = client._execute(runs_query) # _execute is used for raw GraphQL queries
if result and result.get("runsOrError", {}).get("__typename") == "Runs":
print("Recent Dagster Runs:")
for run in result["runsOrError"]["results"]:
print(f" ID: {run['id']}, Status: {run['status']}, Job: {run['pipelineName']}")
elif result and result.get("runsOrError", {}).get("__typename") == "PythonError":
print(f"Error fetching runs: {result['runsOrError']['message']}")
else:
print(f"Unexpected result: {result}")
except Exception as e:
print(f"An error occurred: {e}")
dagster-graphql --version
Debug
Known issues
breakingPython 3.9 support has been dropped. The minimum supported Python version for `dagster-graphql` (and Dagster core) is now 3.10. Users on Python 3.9 must upgrade their Python environment.fixUpgrade Python environment to 3.10 or newer (up to 3.14).
affects: >=1.12.0
deprecatedThe `reload_repository_location` API method in `DagsterGraphQLClient` is slated for removal in Dagster version 2.0.fixReview your code for usage of `client.reload_repository_location` and consult Dagster documentation for alternatives as version 2.0 approaches.
affects: All 1.x versions
gotchaThe `dagster-graphql` package currently includes the entire `dagster` package and its sub-dependencies, which can lead to a large number of transitive dependencies. This might cause dependency clashes in complex environments or when integrating into lightweight applications.fixBe mindful of your dependency tree. If clashes occur, consider isolating environments (e.g., using virtual environments) or manually crafting GraphQL requests if the `DagsterGraphQLClient`'s convenience is outweighed by dependency issues. The core GraphQL API can be interacted with directly using any HTTP client.
affects: All versions
gotchaThe Dagster GraphQL API is still evolving, and certain parts (especially those primarily for internal use by the Dagster webserver) are subject to breaking changes.fixAlways refer to the official Dagster release notes and GraphQL API documentation before upgrading to anticipate and address potential breaking changes, especially if relying on less commonly used API endpoints.
affects: All versions
gotchaWhen querying logs for a run or events, the GraphQL API applies a default limit of 1000 items. To retrieve all logs, you must use the `cursor` field in the response to paginate through subsequent results.fixImplement pagination logic using the `cursor` field when querying `logsForRun` or `eventConnection` resolvers to ensure complete data retrieval.
affects: All versions
gotchaTo reliably fetch job configuration schemas, use the `runConfigSchemaOrError` query rather than trying to extract `runConfigYaml` from `runsOrError`. Old runs or pruned data may result in `runConfigYaml` being empty or omitted, making it unreliable for reconstructing job configurations.fixFor fetching a job's default or current configuration schema, query `runConfigSchemaOrError` directly against the job definition. For past run configurations, be aware of data retention policies.
affects: All versions
Errors
Common errors & fixes
ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
The `DagsterGraphQLClient` cannot establish or maintain a connection with the Dagster GraphQL server, often due to the server being down, an incorrect hostname or port, or network connectivity issues.
fixVerify that the Dagster GraphQL server (typically `dagit`) is running and accessible at the specified `hostname` and `port_number`, and check network configurations or firewalls.
DagsterGraphQLClientError: PipelineNotFoundError
The GraphQL query submitted via the client refers to a pipeline or job name that does not exist in the targeted Dagster repository location.
fixEnsure that the `job_name`, `repository_location_name`, and `repository_name` provided to methods like `submit_job_execution` or `get_run_status` are correct and match an existing definition in your Dagster deployment.
DagsterGraphQLClientError: JobConfigValidationInvalid
The `run_config` provided for a job execution does not conform to the expected configuration schema of that particular Dagster job.
fixReview the job's configuration schema and adjust the `run_config` dictionary to correctly match the required structure and types.
ModuleNotFoundError: No module named 'CODE_LOCATION_NAME_PLACEHOLDER'
The Python environment where Dagster is attempting to load a code location cannot find the specified module, usually because the project is not correctly installed or its structure is misconfigured.
fixEnsure your Dagster project is installed in the Python environment, typically by running `pip install -e .` from your project root, and that all necessary dependencies are present. Also verify the `module_name` in your `workspace.yaml` or `dagster.yaml` is correct.
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: http://yourorg.dagster.cloud/prod/graphql
The request to the Dagster GraphQL API is missing or contains an invalid authentication token/header, leading to an unauthorized access attempt, especially when connecting to Dagster Cloud or a secure self-hosted instance.
fixWhen initializing `DagsterGraphQLClient` for Dagster Cloud, ensure you pass a valid user token in the `headers` parameter as `{'Dagster-Cloud-Api-Token': 'your_token_here'}`. For self-hosted instances with authentication, provide the appropriate headers or authentication mechanism. Upgrade
Version history
1.13.20latest on PyPI · released Aug 27, 2026
Audit
Dependencies
dagsterrequireddagster-graphql is part of the Dagster ecosystem and currently includes the entire 'dagster' package as a dependency, which can lead to a large dependency tree.
gqlrequiredUtilized internally for GraphQL query dispatch over HTTP. Bumped to be inclusive of v4 for broader transitive dependency compatibility.