GraphQL API cookbook

This page provides examples for common API tasks. Want to suggest a recipe? We welcome pull requests to the docs repo.

You can test out the Buildkite API using the Buildkite explorer. This includes built in documentation under the Docs panel.

Get all environment variables set on a build

Retrieve all of a job's environment variables for a given build. This is the equivalent of what you see in the Environment tab of each build.

query GetEnvVarsBuild {
  build(slug:"organization-slug/pipeline-slug/build-number") {
    message
    jobs(first: 10, state:FINISHED) {
      edges {
        node {
          ... on JobTypeCommand {
            label
            env
          }
        }
      }
    }
  }
}

Get build info by ID

Get all the available info from a build while only having its UUID.

query GetBuilds {
  build(uuid: "a00000a-xxxx-xxxx-xxxx-a000000000a") {
    id
    number
    url
  }
}

Get a list of recently created pipelines

Get a list of the 500 most recently created pipelines.

query RecentPipelineSlugs {
  organization(slug: "organization-slug") {
    pipelines(first: 500) {
      edges {
        node {
          slug
        }
      }
    }
  }
}

Get the creation date of the most recent build in every pipeline

Get the creation date of the most recent build in every pipeline. Use pagination to handle large responses. Buildkite sorts builds by newest first.

Get the first 500:

query {
  organization(slug: "organization-slug") {
    pipelines(first: 500) {
      count
      pageInfo {
        endCursor
        hasNextPage
      }
      edges {
        node {
          name
          slug
          builds(first: 1) {
            edges {
              node {
                createdAt
              }
            }
          }
        }
      }
    }
  }
}

Then, if there are more than 500 results, use the value of organization.pipelines.pageInfo.endCursor to get the next page:

query {
  organization(slug: "organization-slug") {
    pipelines(first: 500, after: "value-from-organization.pipelines.pageInfo.endCursor") {
      count
      pageInfo {
        endCursor
        hasNextPage
      }
      edges {
        node {
          name
          slug
          builds(first: 1) {
            edges {
              node {
                createdAt
              }
            }
          }
        }
      }
    }
  }
}

Get all jobs in a given queue for a given timeframe

Get all jobs in a named queue, created on or after a given date. Note that if you want all jobs in the default queue, you do not need to set a queue name, so you can omit the agentQueryRules option.

query PipelineRecentBuildLastJobQueue {
  organization(slug: "organization-slug") {
    pipelines(first: 500) {
      edges {
        node {
          slug
          builds(first: 1) {
            edges {
              node {
                number
                jobs(state: FINISHED, first: 1, agentQueryRules: "queue=queue-name") {
                  edges {
                    node {
                      ... on JobTypeCommand {
                        uuid
                        agentQueryRules
                        createdAt
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Get all jobs in a particular concurrency group

To see which jobs are waiting for a concurrency group in case the secret URL fails, you can use the following query.

query getConcurrency {
  organization(slug: "{org}") {
    jobs(first:100,concurrency:{"name"}, type:[COMMAND], state:[LIMITED]) {
      edges {
        node {
          ... on JobTypeCommand {
            url
            createdAt
          }
        }
      }
    }
  }
}

Get the last job of an agent

To get the last job of an agent or null. You will need to know the UUID of the agent.

query AgentJobs {
  agent(slug: "organization-slug/agent-UUID") {
    jobs(first: 10) {
      edges {
        node {
          ... on JobTypeCommand {
            state
            build {
              state
            }
          }
        }
      }
    }
  }
}

Get pipeline metrics

The Pipelines page in Buildkite shows speed, reliability, and builds per week, for each pipeline. You can also access this information through the API.

query AllPipelineMetrics {
  organization(slug: "organization-slug") {
    name
    pipelines(first: 50) {
      edges {
        node {
          name
          metrics {
            edges {
              node {
                label
                value
              }
            }
          }
        }
      }
    }
  }
}

Count the number of builds on a branch

Count how many builds a pipeline has done for a given repository branch.

query PipelineBuildCountForBranchQuery {
  pipeline(slug:"organization-slug/pipeline-slug") {
    builds(branch:"branch-name") {
      count
    }
  }
}

You can limit the results to a certain timeframe using createdAtFrom or createdAtTo.

query PipelineBuildCountForBranchQuery {
  pipeline(slug:"organization-slug/pipeline-slug") {
    builds(branch:"branch-name", createdAtTo:"DateTime") {
      count
    }
  }
}

List organization members

List the first 100 members in the organization.

query getOrgMembers{
  organization(slug: "organization-slug") {
    members(first: 100) {
      edges {
        node {
          role
          user {
            name
            email
            id
          }
        }
      }
    }
  }
}

Search for organization members

Look up organization members using their email address.

Search
query getOrgMember{
  organization(slug: "buildkite") {
    members(first: 1, search: "jason@buildkite.com") {
      edges {
        node {
          role
          user {
            name
            email
            id
          }
        }
      }
    }
  }
}

Use this to get the last sign-in date for users in your organization, if your organization has SSO enabled.

query getRecentSignOn {
  organization(slug: "organization-slug") {
    members(first: 100) {
      edges {
        node {
          user {
            name
            email
          }
          sso {
            authorizations(first: 1) {
              edges {
                node {
                  createdAt
                  expiredAt
                }
              }
            }
          }
        }
      }
    }
  }
}

Update the default SSO provider session duration

You can control how long the session can go before the user must revalidate with your SSO. By default that's indefinite, but you can reduce it down to hours or days.

mutation UpdateSessionDuration {
  ssoProviderUpdate(input: { id: "ID", sessionDurationInHours: 2 }) {
    ssoProvider {
      sessionDurationInHours
    }
  }
}

Search for an organization member by email address

Get details of a single organization member by their email address.

query getOrgMember{
  organization(slug: "organization-slug") {
    members(first: 1, search: "user-email") {
      edges {
        node {
          role
          user {
            name
            email
            id
          }
        }
      }
    }
  }
}

Get a list of agent token IDs

Get the first five agent token IDs for an organization.

query token {
  organization(slug: "organization-slug") {
    id
    name
    agentTokens(first: 5) {
      edges {
        node {
          id
          description
        }
      }
    }
  }
}

Increase the next build number

Set the number for the next build to run in this pipeline.

First, get the pipeline ID:

query PipelineId {
  pipeline(slug: "organization-slug/pipeline-slug") {
    id
  }
}

Then mutate the next build number. In this example, we set nextBuildNumber to 300:

mutation PipelineUpdate {
  pipelineUpdate(input: {
  id: "pipeline-id",
  nextBuildNumber: 300
  }) {
    pipeline {
      name 
      nextBuildNumber
    }
  }
}

Set teams' pipeline edit access to READ_ONLY or BUILD_AND_READ

Remove edit access from existing teams. This is helpful when you want to centralize pipeline edit permissions to a single system user, controlled by an organization admin.

First, walk through all teams:

query Teams {
  organization(slug: "organization-slug") {
    teams(first: 500) {
      edges {
        node {
          slug
        }
      }
    }
  }
}

Then, get the team pipeline IDs from the team slugs. Use the id returned here as the team-pipeline-id in the next step.

query TeamPipelineIDs {
  team(slug: "organization-slug/team-slug") {
    pipelines(first: 500) {
      edges {
        node {
          id 
        }
      }
    }
  }
}

Finally, update all pipelines in a team to have either READ_ONLY or BUILD_AND_READ access:

mutation UpdateTeamPipelineReadonly {
  teamPipelineUpdate(input: {
    id: "team-pipeline-id",
    accessLevel: BUILD_AND_READ
  }) {
    teamPipeline {
      permissions {
        teamPipelineDelete {
          allowed
          code
          message
        }
        teamPipelineUpdate {
          allowed
          code
          message
        }
      }
    }
    clientMutationId
  }
}

Add an existing organization user to a team

Add an organization member to a team. This does not create a new user.

First, get a list of teams in the organization, to get the team ID:

query getOrgTeams {
  organization(slug: "organization-slug") {
    teams(first: 500) {
      edges {
        node {
          name
          id
        }
      }
    }
  }
}

Then, add a team member. You can get the user-id using the example in Search for an organization member by email address.

📘

clientMutationId is null when the mutation is successful.

mutation addTeamMember{
  teamMemberCreate(input: {teamID: "team-id", userID: "user-id"}) {
    clientMutationId
  }
}

Create a user, add them to a team, and set user permissions

Invite a new user to the organization, add them to a team, and set their role.

First, get the organization and team ID:

query getOrganizationAndTeamId {
  organization(slug: "organization-slug") {
    id
    teams(first:500) {
      edges {
        node {
          id
          slug
        }
      }
    }
  }
}

Then invite the user and add them to a team, setting their role to 'maintainer':

mutation CreateUser {
  organizationInvitationCreate(input: {
    organizationID: "organization-id",
    emails: ["user-email"],
    role: MEMBER,
    teams: [
      {
        id: "team-id",
        role: MAINTAINER
      }
    ]
  }) {
    invitationEdges {
      node {
        email
        createdAt
      }
    }
  }
}

Create a team

Create a new team.

First, get the organization ID:

query getOrganizationId {
  organization(slug: "organization-slug") {
    id
  }
}

Then use the ID to create a new team within the organization:

mutation CreateTeam {
  teamCreate(input: {
    organizationID: "organization-id",
    name: "team-name",
    privacy: SECRET,
    isDefaultTeam: false,
    defaultMemberRole: MEMBER
  }) {
    organization {
      uuid
      teams(first: 1, order: RECENTLY_CREATED) {
        count
        edges {
          node {
            name
          }
        }
      }
    }
  }
}

Create a pipeline

Create a pipeline programmatically.

First, get the organization ID and team ID:

query getOrganizationAndTeamId {
  organization(slug: "organization-slug") {
    id
    teams(first:500) {
      edges {
        node {
          id
          slug
        }
      }
    }
  }
}

Then, create the pipeline:

mutation createPipeline {
  pipelineCreate(input: {
    organizationId: "organization-id"
    name: "pipeline-name",
    repository: {url: "repo-url"},
    steps: { yaml: "steps:\n - command: \"buildkite-agent pipeline upload\"" },
    teams: { id: "team-id" }
  }) {
    pipeline {
      id
      name
      teams(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
}

📘

When setting pipeline steps using the API, you must pass in a string that Buildkite parses as valid YAML, escaping quotes and line breaks.

To avoid writing an entire YAML file in a single string, you can place a pipeline.yml file in a .buildkite directory at the root of your repo, and use the pipeline upload command in your pipeline steps to tell Buildkite where to find it. This means you only need the following:

steps: { yaml: "steps:\n - command: \"buildkite-agent pipeline upload\"" }

Revoke an agent token

Revoking an agent token means no new agents can start using the token. It does not affect any connected agents.

First, get the token ID. You can find it in the Buildkite dashboard, in Agents > Reveal Agent Token, or you can retrieve a list of agent token IDs using this query:

query GetAgentTokenID {
  organization(slug: "organization-slug") {
    agentTokens(first:50) {
      edges {
        node {
          id
          uuid
          description
        }
      }
    }
  }
}

Then, using the token ID, revoke the agent token:

mutation {
  agentTokenRevoke(input: {
    id: "token-id",
    reason: "A reason"
  }) {
    agentToken {
      description
      revokedAt
      revokedReason
    }
  }
}

Remove a team member

This deletes a user from a team, but not from the organization.

First, get a list of teams and members, to get the team IDs and current memberships:

query TeamMembersQuery {
  organization(slug: "organization-slug") {
    teams(first: 500) {
      edges {
        node {
          name
          id
          members(first: 100) {
            edges {
              node {
                role
                id
                user {
                  name
                  email
                  id
                }
              }
            }
          }
        }
      }
    }
  }
}

Then delete a team member. Check that you have the team member ID and not the user ID:

📘

clientMutationId is null when the mutation is successful.

mutation deleteTeamMember {
  teamMemberDelete(input: {id: "team-member-id"}) {
    clientMutationId
  }
}

Delete a pipeline

First, get the ID of the pipeline you want to delete:

query {
  pipeline(slug:"organization-slug/pipeline-slug") {
    id
  }
}

Then, use the ID to delete the pipeline:

mutation PipelineDelete {
  pipelineDelete(input: {
    id: "pipeline-id"
  })
  {
    deletedPipelineID
  }
}

Delete an organization member

This deletes a member from an organization. It does not delete their Buildkite user account.

First, find the member's ID:

query {
  organization(slug: "organization-slug") {
    members(search: "organization-member-name", first: 10) {
      edges {
        node {
          role
          user {
            name
          }
          id
        }
      }
    }
  }

Then, use the ID to delete the user:

mutation deleteOrgMember {
  organizationMemberDelete(input: { id: "organization-member-id" }){
    organization{
      name
    }
    deletedOrganizationMemberID
    user{
        name
    }
  }
}