Build History API - IncrediBuild Documentation

This feature is only available in Incredibuild’s Enterprise Plan. 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 and an Enterprise license. Note that Incredibuild only stores the last 200,000 builds on our database.

Support Matrix

Build Group API Version	Required version of Incredibuild for Windows	Required version of Incredibuild for Linux	Required version of Incredibuild for Mac
1.5.0	10.15 and higher	4.9 and higher	4.9 and higher
1.4.0	X and higher?	X and higher?	X and higher?
1.3.0	X and higher?	X and higher?	X and higher?

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, versions 1.5.0, 1.4.0, and 1.3.0 are 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 after 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}
loggingLevel	Requires API version 1.5.0. Only include builds that match a specific logging level.win only	Integer 1-5

Examples:

Return all builds: GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.5.0
Return builds that started after a particular time: GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.5.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.5.0&buildGroup=Default
Return builds with the build type=Rebuild GET https://10.132.15.166:8000/api/builds?coordinatorId=12345&version=1.5.0&buildType=Rebuild

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.5.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
buildPriority	The priority given to this build over other builds to obtain helpers (1 is the highest, 5 is the lowest)
buildTitle	Meta data that you added to describe this build (optional)
buildStatus	The status of the build upon completion. Can be: Succeeded, Failed, or Canceled.
buildType	Build, Clean, Rebuild, etc.
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)
TotalCoreTime	The total time (seconds) that was used to execute tasks locally or remotely (physical and cloud)
coreLimit	The setting for the maximum number of allowed concurrent helper cores per build
totalCacheableTasks	The total number of tasks whose output can be cached.
cacheTaskHits	When using Build Cache, the number of tasks that were skipped by reusing output from the Build Cache.
cacheTaskMiss	When using Build Cache, the number of tasks that were run after failing to find a match in the Build Cache.
cacheInitiatorRole	Whether the Initiator can only read from the cache, or also write to it.
cacheTaskHitsOriginalDuration	Requires API version 1.4.0 or higher. Duration of all tasks fetched from the Build Cache in milliseconds. (new in 1.4.0, only change from 1.4.0. win only)
cacheServiceEndpoint	The address of the Build Cache service
cacheLicenseAllowed	Whether Build Cache had enough Cache Cores (or Cloud Hours if using Incredibuild for Cloud with Build Cache).
createdAt	The date and time of the API call that generated this response.
loggingLevel	Requires API version 1.5.0 or higher. The logging level of the Agent. 1 is the lowest log level and 5 is the highest. (new in 1.5.0, win only )
agentDescription	Requires API version 1.5.0 or higher. The description of the Initiator Agent that you added in the Agent List. (new in 1.5.0. win and lin and mac)
loggedOnUsers	Requires API version 1.5.0 or higher. A comma-separated list of Windows users that were logged on to the Initiator machine the moment the build started running. (new in 1.5.0, win only )

Example Response for 1.5.0 The following example displays the first build that would be included in this JSON. The response may differ slightly if you are using earlier versions of the API.

{
 "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,

            "buildPriority": 3,

            "buildGroup": "Build Group 17",

            "buildTitle": "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,

            "totalCacheableTasks": 32,

            "cacheTaskHits": 8,

            "cacheTaskMiss": 31,

            "cacheInitiatorRole": 72,

            "savedTime": 81,

            "cacheServiceEndpoint": "endpoint",

            "cacheLicenseAllowed": true,

            "createdAt": "2023-08-20T07:27:30.425Z",
            
            "agentDescription": "My favorite Agent",
            
            "loggedOnUsers": "Harry, Jane",
            
			"loggingLevel": 3
        }]

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:

The average build duration

select build_id ,avg(duration) as avg_duration from builds b group by build_id

How many builds were executed on a particular machine

select initiator_id, count(distinct build_id) as builds from builds b group by initiator_id

How many helpers were involved in a particular build

select build_id , total_working_helpers from builds b

The total time spend executing tasks on remote helper machines

select date(start_time) as date, sum(remote_core_time)/60000 as total_remote_minutes
from builds b
group by 1
order by 1

How many Initiators are active at least once per day

select date(start_time) as date, count(distinct initiator_id) as unique_initiators 
from builds b 
group by 1
order by 1

How many Helpers are active at least once per day

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

How many builds failed per day

SELECT date(start_time) as date,count(build_id) as builds from builds
where build_status not in ('CancelledByUser','Success')
group by date(start_time)

Build Cache analysis

select build_id ,number_of_local_tasks + number_of_remote_tasks as total_tasks, total_cacheable_tasks ,
round(total_cacheable_tasks*1.000/(number_of_local_tasks + number_of_remote_tasks),3)*100 as cacheable_percentage,
cache_task_hits , round(cache_task_hits*1.000 /total_cacheable_tasks,3)*100 as hits_percentage
from builds b
where cache_task_miss + cache_task_hits = total_cacheable_tasks

​Support Matrix

​Request

​Response

​Extracting More from the Data

Support Matrix

Request

Response

Extracting More from the Data