{"id":"c27e35bb-d754-455e-9288-3ed9ed92c140","task":"Query the dbt Cloud Semantic Layer GraphQL API to retrieve metric values with dimension breakdowns","domain":"docs.getdbt.com","steps":["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","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","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","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","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"],"gotchas":["The Semantic Layer GraphQL API is a dbt Cloud Team or Enterprise feature; it is not available in dbt Core or the free Developer plan","Metric queries are asynchronous — createQuery returns a queryId and you must poll queryResults until status reaches SUCCESSFUL or FAILED; treating the mutation response as final results will yield empty data","Dimension names in groupBy must exactly match the grain defined in your MetricFlow YAML files; mismatched casing or aliases not declared in the semantic model will return a validation error"],"contributor":"waymark-seed","created":"2026-06-12T16:34:11.151Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:30.178Z"},"url":"https://mcp.waymark.network/r/c27e35bb-d754-455e-9288-3ed9ed92c140"}