GraphQL

Execute custom GraphQL queries against the Buildkite GraphQL API to retrieve specific data from your Buildkite organization, including pipelines, agents, builds, teams, and other resources.

Sync Type: Configurable (Interval-based)

Requirements

• A Buildkite organization account
• An API token with GraphQL permissions
• Knowledge of Buildkite's GraphQL schema and query structure

Creating an API Token

To create an API token for accessing Buildkite's GraphQL API:

1. Navigate to Personal Settings in your Buildkite account
2. Go to API Access Token section
3. Click New API Access token
4. Fill in a description for the token (e.g., "Monad GraphQL Access")
5. Select your organization from the dropdown menu
6. Check the GraphQL API checkbox to grant GraphQL access permissions
7. Press Create New API token
8. Copy the generated token and use it in the configuration

Note: Store the token securely as it won't be shown again once you leave the page.

Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

Settings

Setting	Type	Required	Description
GraphQL Query	text	Yes	The GraphQL query to execute against the Buildkite API. Must be a valid GraphQL query string.
Interval Seconds	integer	Yes	Time interval in seconds between consecutive API calls. Default: 10 seconds.
Record Location	string	Yes	JSONPath location of the records array in the GraphQL response (e.g., data.organization.pipelines.edges).
Variables	array	No	GraphQL query variables to pass with each request. Each variable has a Name and Value.
Enable Pagination	boolean	Yes	Enable automatic pagination support. Default: false.
Pagination Cursor Path	string	No	JSONPath location for pagination cursor/token (required if pagination is enabled).
Has Next Page Path	string	No	JSONPath location to check if there are more pages (required if pagination is enabled).

Secrets

Secret	Type	Required	Description
Token	string	Yes	Buildkite API token with GraphQL API permissions.

GraphQL Query Examples

Basic Pipeline Query

query GetPipelines($orgSlug: ID!) {
  organization(slug: $orgSlug) {
    pipelines(first: 100) {
      edges {
        node {
          id
          name
          slug
          repository {
            url
          }
          defaultBranch
          visibility
          createdAt
          updatedAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Agents Query

query GetAgents($orgSlug: ID!) {
  organization(slug: $orgSlug) {
    agents(first: 100) {
      edges {
        node {
          id
          name
          hostname
          ipAddress
          operatingSystem
          version
          connectionState
          createdAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Builds Query with Variables

query GetBuilds($orgSlug: ID!, $pipelineSlug: String!, $state: BuildStates) {
  organization(slug: $orgSlug) {
    pipeline(slug: $pipelineSlug) {
      builds(first: 50, state: [$state]) {
        edges {
          node {
            id
            number
            state
            branch
            message
            commit
            createdAt
            startedAt
            finishedAt
            url
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}

Pagination Configuration

For queries returning large datasets, configure pagination:

1. Enable Pagination: Set to true
2. Pagination Cursor Path: data.organization.pipelines.pageInfo.endCursor
3. Has Next Page Path: data.organization.pipelines.pageInfo.hasNextPage
4. Query Variables: Include an after variable in your query for cursor-based pagination

Example paginated query:

query GetPipelines($orgSlug: ID!, $after: String) {
  organization(slug: $orgSlug) {
    pipelines(first: 100, after: $after) {
      edges {
        node {
          # ... fields
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Variables Configuration

Variables allow you to parameterize your queries:

Variable Name	Value	Description
orgSlug	your-org-slug	Your organization slug
pipelineSlug	my-pipeline	Specific pipeline slug
state	RUNNING	Build state filter
first	100	Number of records to fetch

Common Use Cases

• Custom Pipeline Analytics: Query specific pipeline metadata and statistics
• Agent Monitoring: Retrieve detailed agent information and status
• Build Analysis: Fetch build data with custom filters and timeframes
• Team Management: Query team memberships and permissions
• Audit Trail: Retrieve detailed activity logs and changes
• Resource Inventory: Get comprehensive lists of all organization resources

Related Articles

• Buildkite GraphQL API Documentation
• Buildkite GraphQL Explorer
• GraphQL Query Language Guide
• JSONPath Expression Guide

Sample Record

{
  "id": "UGlwZWxpbmU6cGlwZWxpbmUtaWQtMQ==",
  "name": "Production Deploy",
  "slug": "production-deploy",
  "repository": {
    "url": "https://github.com/acme/production-app.git"
  },
  "defaultBranch": "main",
  "visibility": "PRIVATE",
  "createdAt": "2025-08-11T10:30:00Z",
  "updatedAt": "2025-08-11T15:45:22Z"
}