GraphQL API Overview

The Buildkite GraphQL API provides an alternative to the REST API. It allows for more efficient retrieval of data by enabling you to fetch multiple, nested resources in a single request. The Buildkite GraphQL API is currently in beta.

Getting started

The quickest way to get started with the GraphQL API is to generate an API Access Token with GraphQL scope, and then use the GraphQL Explorer with its built-in documentation:

Screenshot of the Buildkite GraphQL Explorer

See our Getting Started Tutorial for a step-by-step guide to using GraphQL queries and mutations.


The GraphQL API endpoint is All requests must be HTTP POST requests with application/json encoded bodies.


GraphQL requests must be authenticated using an API Access Token with the GraphQL scope enabled. Pass the token in your GraphQL request using the Authorization HTTP header with a value Bearer <token>.

For example:

curl -H "Authorization: Bearer $TOKEN"

Performing requests with curl

A GraphQL request is a standard HTTPS POST request, with a JSON-encoded body containing a "query" key, and optionally a "variables" key.

For example, the following curl command returns the name property of the current viewer:

curl \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "{ viewer { user { name } } }",
    "variables": "{ }"
  "data": {
    "viewer": {
      "user": {
        "name": "Jane Doe"

For documentation on the full list of fields and types, see the interactive documentation in the GraphQL Explorer.

Relay compatibility

The Buildkite GraphQL API adheres to the Relay Specification, which defines standards for querying paginated collections ("Connections" and "Edges"), identifying objects directly from the root of a query (avoiding long nested queries), and for providing mutation input data.

Learning more about GraphQL

Further resources for learning more about GraphQL: