Skip to main content

Query the Metadata API

The Metadata API supports ad-hoc queries or lets you browse the schema. If you are new to the API, read the Metadata API overview for an introduction to the Metadata API.

Prerequisites​

Authorization​

Currently, authorization of requests takes place using a service token. dbt Cloud admin users can generate a Metadata Only service token that is authorized to execute a specific query against the Metadata API.

Once you've created a token, you can use it in the Authorization header of requests to the dbt Cloud Metadata API. Be sure to include the Token prefix in the Authorization header, or the request will fail with a 401 Unauthorized error. Note that Bearer can be used in place of Token in the Authorization header. Both syntaxes are equivalent.

Run queries​

You can run queries by sending a POST request to the https://metadata.YOUR_ACCESS_URL/graphql endpoint, making sure to replace:

  • YOUR_ACCESS_URL with the appropriate Access URL for your region and plan.

  • YOUR_TOKEN in the Authorization header with your actual API token.

  • QUERY_BODY with a JSON string, for example { "query": "<query text>" }

    curl 'https://metadata.YOUR_ACCESS_URL/graphql' \
      -H 'authorization: Bearer YOUR_TOKEN' \
      -H 'content-type: application/json'
      -X POST
      --data QUERY_BODY

Every query will rely on a jobID. You can get the jobID by clicking into the relevant job in dbt Cloud and observing the URL. In this example URL, the jobID would be 917: https://YOUR_ACCESS_URL/#/accounts/1/projects/665/jobs/917/

There are several illustrative example queries in this documentation. You can see an example of queries on the Model node.

GraphQL API explorer​

You can run ad-hoc queries directly in the GraphQL API explorer and use the document explorer on the left-hand side, where you can see all possible nodes and fields.

Refer to the Apollo explorer documentation for setup and authorization info.

  1. Access the GraphQL API explorer and select fields you'd like query.
  2. Go to Variables at the bottom of the explorer and replace any null fields with your unique fields.
  3. Authenticate via bearer auth with YOUR_TOKEN. Go to Headers at the bottom of the explorer and select +New header.
  4. Select Authorization in the header key drop-down list and enter your Bearer auth token in the value field.
  5. Run your query by pressing the blue query button in the top-right of the Operation editor (to the right of the query). You should see a successful query response on the right side of the explorer.
Run queries using the Apollo Server GraphQL explorerRun queries using the Apollo Server GraphQL explorer
0
Edit this page