Query the dbt Cloud Semantic Layer GraphQL API to retrieve metric values with dimension breakdowns

Steps

1. Enable the dbt Semantic Layer in your dbt Cloud environment and obtain the Environment ID and a service token (or personal access token) from Account Settings in dbt Cloud
2. Connect to the GraphQL API endpoint at https://semantic-layer.cloud.getdbt.com/api/graphql using the header Authorization: Bearer YOUR_SERVICE_TOKEN and the query parameter environmentId=YOUR_ENV_ID
3. Introspect available metrics by sending the query { metrics(environmentId: YOUR_ENV_ID) { name description type } } to discover what metrics are defined in your semantic layer
4. Query metric values with dimensions using the createQuery mutation to create a query, then poll queryResults with the returned queryId; the createQuery payload accepts metrics, groupBy, where, and orderBy fields
5. Parse the paginated results from queryResults; as of 2025, paginated GraphQL endpoints for metadata queries are available to handle large manifests and avoid timeouts on environments with many models