# 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      | Location of the records array in the GraphQL response. See [Record Location](../../../guides/record-location) for syntax and examples. |
| 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
```graphql
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
```graphql
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
```graphql
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:
```graphql
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](https://buildkite.com/docs/apis/graphql-api)
- [Buildkite GraphQL Explorer](https://graphql.buildkite.com/explorer)
- [GraphQL Query Language Guide](https://graphql.org/learn/queries/)
- [JSONPath Expression Guide](https://goessner.net/articles/JsonPath/)

## Sample Record

```json
{
  "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"
}
```