The Gradle Enterprise API allows programmatic interaction with various aspects of Gradle Enterprise, from configuration to inspecting build data.

Fundamentals

The Gradle Enterprise API is a REST-style API using JSON as the data format.

OpenAPI

The API is defined using the OpenAPI standard, which is a declarative specification that allows tools and libraries to generate client code. The specification can be found in the Reference section.

Versioning and compatibility

The API is generally backwards compatible.

New functionality (e.g. endpoints, response attributes) may be added in new major versions (i.e. 2022.1, 2022.2).

Breaking changes will occur infrequently if at all, and only after a reasonable deprecation period. Deprecations will be communicated by:

  • The release notes for the major Gradle Enterprise version introducing the deprecation.

  • The deprecated annotation within the OpenAPI specification.

  • The Deprecated HTTP response header (indicating when the operation was deprecated).

  • The Sunset HTTP response header (indicating when the operation will be removed).

API documentation may be refined in patch releases, along with implementation defects that cause deviation from the specification.

Getting started

Access control

All requests must provide a Gradle Enterprise access key as “bearer token”.

To create an access key:

  1. Sign in to Gradle Enterprise.

  2. Access "My settings" from the user menu in the top right-hand corner of the page.

  3. Access "Access keys" from the left-hand menu.

  4. Click "Generate" on the right-hand side and copy the generated access key.

Different requests require different user permissions, as describe via the API specification.

To view the permissions assigned to you:

  1. Sign in to Gradle Enterprise.

  2. Access "My settings" from the user menu in the top right-hand corner of the page.

  3. Access "Permissions" from the left-hand menu.

  4. Check if you have the required permissions.

If you do not have the required permission, contact your Gradle Enterprise administrator.

Making a request

The following example demonstrates using cURL to make a request to the builds endpoint, which requires the “Access build data via the API” permission.

$ curl -H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja" "https://ge.mycompany.com/api/builds?since=0&maxBuilds=3"
[
  {
    "id": "7asfp6iy3d5ey",
    "availableAt": 1645452789334,
    "buildToolType": "gradle",
    "buildToolVersion": "7.4",
    "buildAgentVersion": "3.8.1"
  },
  {
    "id": "1saxebtd5d4xs",
    "availableAt": 1645452795414,
    "buildToolType": "maven",
    "buildToolVersion": "3.8.4",
    "buildAgentVersion": "1.12.4"
  },
  {
    "id": "hx4k23knk64ri",
    "availableAt": 1645453205526,
    "buildToolType": "gradle",
    "buildToolVersion": "7.4",
    "buildAgentVersion": "3.8.1"
  }
]

The builds endpoint can be used to discover the builds observed by the system. This example fetches the 3 oldest builds due to the since=0&maxBuilds=3 parameters.

Next steps

Check out the sample project.

To learn more about the functionality provided by the API and what you can do with it, see Reference.

Reference

The reference documentation is useful for discovering the functionality of the API.

The reference specification is the API described using the OpenAPI standard and is useful for generating client code with OpenAPI-based tooling.

2023.3

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2023.2

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2023.1

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2022.4

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2022.3

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2022.2

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

2022.1

Documentation

Specification (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

Appendix A: About the Export API

The Gradle Enterprise API described in this document will eventually replace the Gradle Enterprise Export API. At this time, the Gradle Enterprise API does not allow consuming the raw events of a build as the Export API does.

If your existing usage of the Export API can be replaced with the easier-to-use Gradle Enterprise API, please consider migrating. For assistance, please contact Gradle Enterprise support.

Appendix B: Release history

2023.3

13th September 2023

  • Add hasVerificationFailure and hasNonVerificationFailure attributes on the /api/builds/{id}/gradle-attributes and /api/builds/{id}/maven-attributes operation response

  • Introduce optional query query parameter for the on the /api/builds endpoint, which can be used to filter the set of returned builds. This parameter’s value should be a URL encoded text query written in the advanced query language (the same advanced query language that is used in the scans list UI).

2023.2

18th July 2023

  • Add effectiveWorkUnitExecutionTime and serialWorkUnitExecutionTime on the /api/builds/{id}/gradle-build-cache-performance operation response

  • Exclude potential artifact transforms from effectiveTaskExecutionTime and serialTaskExecutionTime on the /api/builds/{id}/gradle-build-cache-performance operation response

  • Add cacheArtifactRejectedReason to /api/builds/{id}/gradle-build-cache-performance and /api/builds/{id}/maven-build-cache-performance operation response

2023.1

12th April 2023

  • Add cacheArtifactSize to /api/builds/{id}/gradle-build-cache-performance and /api/builds/{id}/maven-build-cache-performance operation response

  • Add excludedTasks to /api/builds/{id}/gradle-attributes operation response

2022.4

8th December 2022

  • Add new /api/test-distribution/* endpoints for managing API keys and agent pools

  • Add new /api/builds/{id}/gradle-projects endpoint

  • Add new /api/builds/{id}/maven-modules endpoint

  • Introduce fromInstant, fromBuild, reverse query parameters on the /api/builds operation query

  • Deprecate since and sinceBuild query parameters on the /api/builds operation query

2022.3

10th August 2022

  • Add taskExecution.nonCacheabilityCategory and taskExecution.nonCacheabilityReason to /api/builds/{id}/gradle-build-cache-performance operation response

  • Add goalExecution.nonCacheabilityCategory and goalExecution.nonCacheabilityReason to /api/builds/{id}/maven-build-cache-performance operation response

  • Add taskExecution.taskType to /api/builds/{id}/gradle-build-cache-performance operation response

  • Add goalExecution.mojoType to /api/builds/{id}/maven-build-cache-performance operation response

  • Add buildCaches.remote.type to /api/builds/{id}/gradle-build-cache-performance operation response

  • Add buildCaches.remote.className to /api/builds/{id}/gradle-build-cache-performance operation response

  • Add a title to /api/builds inlined query parameters schema

2022.2

19th April 2022

  • Improve OpenAPI specification examples

  • Add buildCaches.local.isPushEnabled to /api/builds/{id}/maven-build-cache-performance operation response

2022.1

17th March 2022

  • Initial release

Appendix C: Advanced query syntax

Gradle Enterprise supports the use of an advanced query language for filtering Build Scan data in the dashboards from version 2022.4, and in the Enterprise API from version 2023.3.

Each query can be made from one or more terms separated by spaces. Each term is a field name and search pattern: fieldName:pattern. For example, project:my-project is equivalent to entering my-project in the Project field in the basic search.

Supported fields

Generic fields

These fields are applicable for builds from all supported build tools.

Name Description Data type Example

user

Username of the OS account that executed the build.

String

user:dylan

hostname

Public hostname of the build machine.

String

hostname:*.somedomain.com

project

Name of the Gradle root project, Maven top level module, Bazel workspace, or Sbt root project.

String

project:my-project

requested

Tasks, goals, or targets that were requested when the build was invoked.

String

requested:":my-project:*"

buildTool

Must be one of gradle, maven, or bazel. In the Build Scan dashboards, but not in the Enterprise API, you can also use the value sbt.

String

buildTool:gradle

buildToolVersion

Version of the build tool that executed the build.

String

buildToolVersion:8.*

value

Custom values added to the Build Scan in the form name=value.

Key-value pair

value:"Git branch=abc/my-feature"

tag

Tags added to the Build Scan.

String

tag:CI

buildOutcome

succeeded or failed.

String

buildOutcome:failed

buildDuration

Duration of the build.

Duration

buildDuration>30m

buildStartTime

Start time of the build.

Timestamp

  • buildStartTime:[2023-01-01 to 2023-02-01]

  • buildStartTime:[2023-09-01T13:00:00 to 2023-09-01T15:00:00]

  • buildStartTime>-5d

Gradle-specific fields

Fields whose name is prefixed with "gradle." are specific to Gradle and select only Gradle builds.

Name Description Data type Example

gradle.rootProjectName

The root project name for the Gradle build.

String

gradle.rootProjectName:foo

gradle.requestedTasks

The resolved set of requested tasks for the Gradle build.

String

gradle.requestedTasks:verify

gradle.pluginVersion

The applied version of the Gradle Enterprise Gradle plugin.

String

gradle.pluginVersion:3.*

Maven-specific fields

Fields whose name is prefixed with "maven." are specific to Maven and select only Maven builds.

Name Description Data type Example

maven.topLevelProjectName

The name of the top level Maven project.

String

maven.topLevelProjectName:foo

maven.requestedGoals

The resolved set of requested goals for the Maven build.

String

maven.requestedGoals:verify

maven.extensionVersion

The applied version of the Gradle Enterprise Maven extension.

String

maven.extensionVersion:1.18.*

Bazel-specific fields

Fields whose name is prefixed with "bazel." are specific to Bazel and select only Bazel builds.

Name Description Data type Example

bazel.requestedTargets

The resolved set of requested targets for the Bazel build.

String

bazel.requestedTargets:*test*

sbt-specific fields

Fields whose name is prefixed with "sbt." are specific to sbt and select only sbt builds.

Name Description Data type Example

sbt.rootProjectName

The name of the top level sbt project.

String

sbt.rootProjectName:foo

sbt.requestedTasks

The resolved set of requested tasks for the sbt build.

String

sbt.requestedTasks:test

sbt.pluginVersion

The applied version of the Gradle Enterprise sbt plugin.

String

sbt.pluginVersion:0.9

Field data types

Every supported field in the advanced query language is associated with one data type. A field’s data type indicates what values it accepts, and each has its own syntax. The data types are all described below.

Data type Description

String

Strings can be exact matches or use the * wildcard. Whitespace and special characters need to be double-quoted. Searches are case-insensitive.

  • project:my-project

  • tag:"Tag with spaces"

  • hostname:*.somedomain.com

Key-value pair

These take the form fieldName:key=value, with wildcards allowed and double-quoting required for whitespace and special characters.

  • value:"Git branch=abc/my-feature"

  • value:ci-agent=*.subdomain.com

Duration

Durations can be specified using ISO 8601 duration syntax or a simple syntax like 5m or 24h.

  • buildDuration>30m

  • buildDuration<=PT2H5.123S

Timestamp

Timestamps can be specified in a few different ways.

  • YYYY-MM-DD - timestamp is at midnight on that day.

  • YYYY-MM-DDTHH:MM - seconds and milliseconds optional.

  • YYYY-MM-DDTHH:MM:SS.SSS

All timestamps can have an optional timezone offset appended in the form Z or +HH:SS to be specific about which timezone the timestamp is being specified in. Default is timezone of the current web browser when using advanced search in Build Scan dashboards. Default is always UTC when using the Enterprise API.

Timestamps in the form of a date can be queried using equality.

  • buildStartTime:2023-09-01 - builds that ran on this day, UTC.

  • buildStartTime:2023-09-01+01:00 - builds that ran on this day, BST (i.e. UTC+1).

Timestamps can be queried using ranges in the form [start to finish].

  • buildStartTime:[2023-01-01 to 2023-02-01] - builds that ran from the Jan 1st - Feb 1st, inclusive.

  • buildStartTime:[2023-09-01T13:00:00 to 2023-09-01T15:00:00] - builds that ran on Sep 1st from 1pm to 3pm.

A timestamp can also be specified relative to the current time using duration syntax.

  • buildStartTime>-5d - builds in the last 5 days.

  • buildStartTime:[2023-01-01T05:23:30Z to -12h] - builds that ran from the start timestamp, until 12 hours ago.

Combining terms

By default, all terms must match.

Terms can be combined using boolean and and or operators, and grouped using parentheses.

  • user:dylan or (tag:CI and value:branch=dylan/*)

Terms can also be negated using - or not.

  • project:my-project -tag:local

  • user:dylan or not (tag:CI and value:branch=dylan/*)