Build History API

You can receive data about your builds in a JSON file. This allows you to take this data and view it in dashboards using third party tools, as well as store it for reference and analysis.

The data can be filtered by time, build group, and other fields. This API requires an API Key.

Note that Incredibuild only stores the last 200,000 builds on our database.

Request

 Endpoint

GET https://<coordinator IP>:8000/api/builds?coordinatorId=<coordinator ID>&version=<API version>&<other filters>

Where version is the version of the Incredibuild API. For the Build Data API, only version 1.3.0 is currently supported.

Header

The request must include a header with a key called client-api-key and the value of your API Key as a string.

Endpoint Filters:

You can add any of the following filters to the request endpoint to limit the results:

Field Values Values
buildStartTimeFrom Only include builds that started before this time ISO format. For example: 2022-09-28T16:01:29.000
buildEndTimeTo Only include builds that ended before this time ISO format. For example: 2022-09-28T16:01:29.000
initiatorID Only include builds initiated by a specific Initiator string
buildGroup Only include builds run by initiators in a specific Build Group string
buildTitle Only include builds with the specified title string

buildStatus

Only include builds that match a specific status

{a,b,c,d}

buildDurationFrom

Only include builds that were at least this long

integer (seconds)

buildDurationTo

Only include builds that were shorter than this value.

integer (seconds)

buildType

Only include builds that match a specific build type

{Build, Clean, Rebuild, Unknown}

Examples:

  • Return all builds:

    GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.3.0

  • Return builds that started after a particular time:

    GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.3.0&buildStartTimeFrom=2023-08-17T16:01:29.000Z

  • Return builds run from the Default Build Group: 

    GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.3.0&buildGroup=Default

If your results return more than 300 builds, you will see that the totalCount is greater than 300, but the value of buildsCount is 300 (as seen in the example below). To view the next 300, copy the value of the nextPageToken and use it in another request as follows:

GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.3.0&nextPageToken="<value in JSON below>"

Response

The response is a JSON file that includes up to 300 builds.

Field Description
totalCount Total number of builds that match the request
buildsCount Number of builds included in this JSON. If this number is less than totalCount, it means that there are more than 300 builds and they cannot all be included in a single JSON. To view the next 300, copy the nextPageToken value and use it as a parameter in another request. For example: GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.3.0&nextPageToken="NjAw"
nextPageToken See buildsCount
builds

An array of the builds included in the file
coordinatorId

The ID of the Coordinator associated with this build
buildId

The ID of the build
initiatorId

The ID of the agent that initiated the build
startTime

The time the build was started
endTime

The time the build ended
duration

The length of the build in seconds

buildCaption

Meta data that you added to describe this build (optional)
buildStatus

The status of the build upon completion
helpers

The list of helpers that participated in this build

totalWorkingHelpers

The total number of unique helpers that assisted in this build

maxInitiatorCores

The maximum number of Initiator cores used to run this build

avgInitiatorCores

The average number of Initiator cores used to run this build

maxConcurrentWorkingHelpers

The maximum number of unique helpers working at one time during this build

avgConcurrentWorkingHelpers

The average number of unique helpers working at one time during this build

avgBusyHelperCores

The average number of helper cores working at one time during this build

maxBusyHelperCores

The maximum number of helper cores working at one time during this build

avgBusyCloudHelperCores

The average number of Cloud helper cores working at one time during this build

maxBusyCloudHelperCores

The maximum number of Cloud helper cores working at one time during this build

maxNeededHelperCores

The maximum number of helper cores requested

avgNeededHelperCores

The average number of helper cores requested

numberOfLocalTasks

Total number of tasks executed on the Initiator for this build

numberOfRemoteTasks

Total number of tasks that were executed remotely

numberOfCloudTasks

Total number of tasks that were executed remotely on Cloud machines

remoteCoreTime

The total time (seconds) that was used to execute tasks remotely (physical and cloud)

coreLimit

The setting for the maximum number of allowed concurrent helper cores per build

createdAt

The date and time of the API call that generated this response.

Field Description

Example Response

The following example displays the first build that would be included in this JSON:

Copy 
{
 "totalCount":400
 "buildsCount":300
 "nextPageToken":"NjAw"
 "builds": [

        {

            "coordinatorId": "c407c0b4-b257-490a-91da-70b7bb5f0c8f",

            "buildId": "{0312b602-8d53-4443-afe5-2bd9f00c33d7}",

            "initiatorId": "64b4d714-fcde-4768-82ac-cdbdfbfa5343",

            "initiatorName": "Initiator#313",

            "startTime": "2023-08-18T20:05:42.708Z",

            "endTime": "2023-08-18T22:41:27.097Z",

            "duration": 9344389,

            "buildGroup": "Build Group 17",

            "buildCaption": "Build Title 5",

            "buildStatus": "Failure",

            "buildType": "Rebuild",

            "helpers": [

                "helper0",

                "helper1",

                "helper2",

                "helper3",

                "helper4",

                "helper5",

                "helper6",

                "helper7",

                "helper8",

                "helper9",

                "helper10",

                "helper11",

                "helper12",

                "helper13",

                "helper14",

                "helper15",

                "helper16",

                "helper17",

                "helper18",

                "helper19",

                "helper20"

            ],

            "totalWorkingHelpers": 9,

            "maxInitiatorCores": 48,

            "avgInitiatorCores": 94,

            "maxConcurrentWorkingHelpers": 97,

            "avgConcurrentWorkingHelpers": 91,

            "avgConcurrentBusyHelpers": 1,

            "maxConcurrentBusyHelpers": 30,

            "avgConcurrentBusyCloudHelpers": 50,

            "maxConcurrentBusyCloudHelpers": 59,

            "maxNeededHelperCores": 29,

            "avgNeededHelperCores": 84,

            "numberOfLocalTasks": 36,

            "numberOfRemoteTasks": 83,

            "numberOfCloudTasks": 94,

            "remoteCoreTime": 78,

            "coreLimit": 11,            

            "createdAt": "2023-08-20T07:27:30.425Z"

        }]

Extracting More from the Data

Once you have downloaded the build history, you can access it in the database of your choice. This allows you to query the data and learn more. Here are some example queries:

Copy 
select build_id ,avg(duration) as avg_duration from builds b group by build_id
Copy 
select initiator_id, count(distinct build_id) as builds from builds b group by initiator_id
Copy 
select build_id , total_working_helpers from builds b
Copy 
select date(start_time) as date, sum(remote_core_time)/60000 as total_remote_minutes
from builds b
group by 1
order by 1
Copy 
select date(start_time) as date, count(distinct initiator_id) as unique_initiators 
from builds b 
group by 1
order by 1
Copy 
WITH RECURSIVE split_cte (start_time ,build_id , helpers , rest) AS (
    SELECT
        start_time,
        build_id ,
        SUBSTR(SUBSTRING(helpers,2,LENGTH(helpers)-1) , 1, INSTR(helpers, ',')-2),
        SUBSTR(helpers , INSTR(helpers, ',')+1)
    FROM builds
    WHERE total_working_helpers > 1
    UNION ALL
    SELECT
        start_time,
        build_id ,
        SUBSTR(rest, 1, INSTR(rest, ',')-1),
        SUBSTR(rest, INSTR(rest, ',')+1)
    FROM split_cte
    WHERE INSTR(rest, ',') > 0
    UNION ALL
    SELECT
        start_time,
        build_id ,
        substring(rest,1,LENGTH(rest)-1),
        NULL
    FROM split_cte
    WHERE INSTR(rest, ',') = 0
)
-- Select the split values
select date(start_time) as date, count(distinct helpers)
from 
    (SELECT start_time,build_id, helpers
    FROM split_cte
    UNION ALL
    SELECT start_time,build_id, helpers
    FROM split_cte
    WHERE rest IS NOT NULL
    union all 
    select start_time,build_id,SUBSTRING(helpers,2,LENGTH(helpers)-2)
    from builds
    where total_working_helpers=1)
group by date(start_time)
order by 1
Copy 
SELECT date(start_time) as date,count(build_id) as builds from builds 
where build_status = 'SystemErrorOrUserInterrupt' 
group by date(start_time)
Copy 
select build_group, date(start_time) as date, count(build_id)  
from builds b 
group by build_group, date(start_time)
order by 1,2
Copy 
select build_group , count(distinct initiator_id) as unique_initiators 
from builds b 
group by 1

WITH RECURSIVE split_cte (build_group ,build_id , helpers , rest) AS (
    SELECT
        build_group ,
        build_id ,
        SUBSTR(SUBSTRING(helpers,2,LENGTH(helpers)-1) , 1, INSTR(helpers, ',')-2),
        SUBSTR(helpers , INSTR(helpers, ',')+1)
    FROM builds
    WHERE total_working_helpers > 1
    UNION ALL
    SELECT
        build_group,
        build_id ,
        SUBSTR(rest, 1, INSTR(rest, ',')-1),
        SUBSTR(rest, INSTR(rest, ',')+1)
    FROM split_cte
    WHERE INSTR(rest, ',') > 0
    UNION ALL
    SELECT
        build_group,
        build_id ,
        substring(rest,1,LENGTH(rest)-1),
        NULL
    FROM split_cte
    WHERE INSTR(rest, ',') = 0
)
-- Select the split values
select build_group, count(distinct helpers)
from 
    (SELECT build_group,build_id, helpers
    FROM split_cte
    UNION ALL
    SELECT build_group,build_id, helpers
    FROM split_cte
    WHERE rest IS NOT NULL
    union all 
    select build_group,build_id,SUBSTRING(helpers,2,LENGTH(helpers)-2)
    from builds
    where total_working_helpers=1)
group by build_group
Copy 
WITH RECURSIVE split_cte (start_time ,build_id , helper , rest) AS (
    SELECT
        start_time,
        build_id ,
        SUBSTR(SUBSTRING(helpers,2,LENGTH(helpers)-1) , 1, INSTR(helpers, ',')-2),
        SUBSTR(helpers , INSTR(helpers, ',')+1)
    FROM builds
    WHERE total_working_helpers > 1
    UNION ALL
    SELECT
        start_time,
        build_id ,
        SUBSTR(rest, 1, INSTR(rest, ',')-1),
        SUBSTR(rest, INSTR(rest, ',')+1)
    FROM split_cte
    WHERE INSTR(rest, ',') > 0
    UNION ALL
    SELECT
        start_time,
        build_id ,
        substring(rest,1,LENGTH(rest)-1),
        NULL
    FROM split_cte
    WHERE INSTR(rest, ',') = 0
)
-- Select the split values
select date(start_time) as date, helper, count(distinct build_id) as builds
from 
    (SELECT start_time,build_id, helper
    FROM split_cte
    UNION ALL
    SELECT start_time,build_id, helper
    FROM split_cte
    WHERE rest IS NOT NULL
    union all 
    select start_time,build_id,SUBSTRING(helpers,2,LENGTH(helpers)-2)
    from builds
    where total_working_helpers=1)
group by date(start_time),helper
order by 1, 3 desc
Copy 
select initiator_id ,count(distinct initiator_id) as initiators
from builds b 
group by 1
Copy 
with recursive builds_active_seconds (date,build_id,start_timestamp, sec, end_timestamp) as (
    select date(start_time),build_id ,min(datetime(start_time)),min(datetime(start_time)),max(datetime(end_time)) 
    from builds b 
    group by date(start_time),2
    union all
    select date,build_id ,start_timestamp,datetime(sec,'+1 second'),end_timestamp
    from builds_active_seconds
    where sec<end_timestamp
    )

select date,count(distinct sec)/60 as grid_active_minutes 
from builds_active_seconds
group by 1
Copy 
SELECT distinct date(start_time) as date,build_status,
    count(build_id) over (partition by date(start_time),build_status)*1.00/count(build_id) over (partition by (date(start_time))) as percentage_of_daily_builds
from builds b 
order by 1,2 
Copy 
with recursive builds_active_seconds (date,build_id,start_timestamp, sec, end_timestamp) as (
    select date(start_time),build_id ,min(datetime(start_time)),min(datetime(start_time)),max(datetime(end_time)) 
    from builds b 
    group by date(start_time),2
    union all
    select date,build_id ,start_timestamp,datetime(sec,'+1 second'),end_timestamp
    from builds_active_seconds
    where sec<end_timestamp
    ),

    concurrent_build_count as (select date,sec,count(build_id) as concurrent_builds
    from builds_active_seconds
    group by 1,2)
    
select date,max(concurrent_builds) as max_concurrent_builds
from concurrent_build_count
group by 1