The Gradle Enterprise Export API allows you to pull out build data from your Gradle Enterprise instance - making it easy to push your build data into other systems and use your build data for internal dashboards and graphs.

Gradle Enterprise is a commercial product for companies that can be hosted on their own systems and provides some additional features on top of the ones available in Gradle Cloud Services. You can learn more about Gradle Enterprise and Gradle Cloud Services at our website.

Overview

The Export API is available at https://gradle.my-company.com/build-export/v1/ and provides a number of Server-Sent Event (SSE) based resources over HTTPS.

The precise URL you need depends on the hostname your Gradle Enterprise instance has been configured with.

There are two types of resources:

  1. Build listing - a potentially infinite stream of builds, containing summary data about the build.

  2. Individual build information - a finite stream of build information modelled as a series of build events.

To get started, you simply need to connect to a resource with your favourite SSE client and begin listening for messages. You can even just copy a resource URL into your browser or cURL to a resource to begin receiving data.

Stream all builds received from now onwards, in real-time
$ curl https://gradle.my-company.com/build-export/v1/builds/since/now?stream

For a more complete example, please see the examples section below. Or visit our GitHub repository of examples, and maybe even contribute your own!

Server-Sent Events (SSE)

Server-Sent Events (SSE) is an API for continuously receiving push based notifications from a server, once a client has established a client-server HTTP connection.

With its event based approach and a defined mechanism for reconnect-resume, SSE is ideal for real-time streaming of events from server to client but also an efficient way of streaming large volumes of data.

For more information, see the W3C specification.

Compression

All of the Export API resources detailed below support gzip compression which will considerably reduce the amount of data being sent over the wire. Compression can be enabled by simply adding the header Accept-Encoding: gzip to your request.

With curl, this can be achieved by passing the argument --compressed like so:

Stream all builds received from now onwards, in real-time and compressed
$ curl --compressed https://gradle.my-company.com/build-export/v1/builds/since/now?stream

Reconnect-resume

All Export API SSE messages will have their id field set, allowing you to take advantage of reconnect-resume functionality should the connection drop.

Connecting to a resource with the Last-Event-ID http header set will resume the stream from that point. In the case of a stream that has no further messages to emit and is complete, a response status of 204 No Content will be returned and further reconnection attempts should not be attempted.

Some SSE clients include this functionality out-of-the-box.

In the case of build listing resources, any build received since the time of the original request will now also be included in the resumed stream.

Client libraries

Most modern browsers implement a JavaScript SSE client. See here for browser compatibility information.

There are also a plethora of SSE clients implemented in various languages, and a quick internet search will reveal the options for your language of choice. Some are listed below for your convenience:

Resources

Build listing

Unless you are using real-time streaming, only builds received up to the time of request will be streamed. Any builds received after that time will not be included in the response stream, even if streaming is still in progress.

GET /builds/since/:date[?stream]

Stream summary build data for all builds since the given date, inclusive.

Parameters

:date

Required

A unix-epoch-time value.
Builds will be returned inclusive of this time. Times in the future are invalid and will result in an error response.
A value of 0 will stream all builds.
A value of now will stream all builds since the current time. To be used in conjunction with real-time streaming.

stream

Optional

Enable real-time streaming.

Response

A stream of messages of type Build.

Example requests
Stream all builds received since June 23, 2016 until now
https://gradle.my-company.com/build-export/v1/builds/since/1466640000000
Stream all builds received since January 01, 1970 until now
https://gradle.my-company.com/build-export/v1/builds/since/0
Stream all builds received from now onwards, in real-time
https://gradle.my-company.com/build-export/v1/builds/since/now?stream

GET /builds/sinceBuild/:buildId[?stream]

Stream summary build data for all builds received since the given build id, exclusive.

Parameters

:buildId

Required

The 13 character id of the build.

stream

Optional

Enable real-time streaming.

Response

A stream of messages of type Build.

Example requests
Stream all builds received since the build with the id gkoprlkauv35q was received until now
https://gradle.my-company.com/build-export/v1/builds/sinceBuild/gkoprlkauv35q
Stream all builds received since the build with the id gkoprlkauv35q was received and all future builds
https://gradle.my-company.com/build-export/v1/builds/sinceBuild/gkoprlkauv35q?stream

Real-time streaming

Real-time streaming can be enabled by supplying the stream query parameter on build listing resources.

Stream all builds received from now onwards, in real-time
https://gradle.my-company.com/build-export/v1/builds/since/now?stream

When enabled, the stream never completes and clients will be notified of builds as soon as they are received by your Gradle Enterprise instance.

Real-time streaming can be used in conjunction with streaming historic build data and also supports reconnect-resume i.e. you can export all previous build data and all future build data in a single fault tolerant stream.

Stream all builds received since June 23, 2016 and all future builds
https://gradle.my-company.com/build-export/v1/builds/since/1466640000000?stream
Stream all builds received since the build with the id gkoprlkauv35q was received and all future builds
https://gradle.my-company.com/build-export/v1/builds/sinceBuild/gkoprlkauv35q?stream

In order to keep the client-server connection alive during periods of inactivity, a "heart beat" message is periodically sent and can be safely ignored.

Individual build information

GET /build/:buildId/events[?eventTypes=type1,type2,…​]

Stream build information for an individual build.

Whilst running a build, build data is mapped to a series of events. The combination of build scan plugin and Gradle version used to run the build will determine what events are produced and at what version. You can see the full list of events in the Javadoc of the Gradle Enterprise Event Model. These events are serialized as JSON and streamed as the data attribute of BuildEvent messages.

It is recommended to specify the event types you require whenever possible to reduce the amount of data streamed.

Parameters

:buildId

Required

The 13 character id of the build.

eventTypes

Optional

A comma separated list of BuildEvent event types.
Event types are case sensitive and only BuildEvent messages whose event type is included in this list will be streamed.
Omitting the query parameter entirely will result in all BuildEvent messages being streamed.
See the Javadoc of the Gradle Enterprise Event Model for a list of valid event types.

Response

A stream consisting of the following messages in strict order:

Example request
Stream all events for the build with the id gkoprlkauv35q
https://gradle.my-company.com/build-export/v1/build/gkoprlkauv35q/events
Stream only the BuildStarted and BuildFinished events for the build with the id gkoprlkauv35q
https://gradle.my-company.com/build-export/v1/build/gkoprlkauv35q/events?eventTypes=BuildStarted,BuildFinished

SSE message types

Build

Summary data for an individual build.

id: gkoprlkauv35q
event: Build
data: {
    "buildId": "gkoprlkauv35q",
    "pluginVersion": "1.6",
    "gradleVersion": "3.3",
    "timestamp": 1466640000000
}
Table 1. Attribtes

buildId

The 13 character id of the build.

pluginVersion

The build scan plugin version used to publish the build.

gradleVersion

The Gradle version used to run the build.

timestamp

The time the build was received by the build scan system as a unix-epoch-time value.

BuildEvent

Information about a particular event that occurred during a build.

Message data is event type and version specific. You can discover what data to expect by using the Javadoc of the Gradle Enterprise Event Model. Note that some event types have an empty data payload.

id: 1
event: BuildEvent
data: {
    "timestamp":1466640000000,
    "type": {
        "majorVersion": 1,
        "minorVersion": 0,
        "eventType": "BuildStarted"
    },
    "data": {}
}
id: 2
event: BuildEvent
data: {
    "timestamp": 1466640000001,
    "type": {
        "majorVersion": 1,
        "minorVersion": 0,
        "eventType": "BuildRequestedTasks"
    },
    "data": {
        "excluded": [],
        "requested": ["build"]
    }
}
Table 2. Attributes

timestamp

The time the event occurred as a unix-epoch-time value.

type

The specific type of the event, including event type, major and minor version. To be used in data parsing.

data

A JSON object containing properties specific to the event type and version. See the Javadoc of the Gradle Enterprise Event Model for details about specific event types.

Examples

Please see the Export API samples GitHub repository for working example usages of the Export API in Java and JavaScript.