> ## Documentation Index > Fetch the complete documentation index at: https://docs.incredibuild.com/llms.txt > Use this file to discover all available pages before exploring further. # Build History API Last updated on Nov 21, 2023 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](/linux/4.2.0/api-keys). Note that Incredibuild only stores the last 200,000 builds on our database. ## Request **Endpoint** ``` GET https://:8000/api/builds?coordinatorId=&version=& ``` 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](/linux/4.2.0/api-keys) 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="" ``` ## 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](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 on physical machines (not cloud) | | 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](javascript:void\(0\);) ``` { "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](javascript:void\(0\);) ``` select build_id ,avg(duration) as avg_duration from builds b group by build_id ``` [Copy](javascript:void\(0\);) ``` select initiator_id, count(distinct build_id) as builds from builds b group by initiator_id ``` [Copy](javascript:void\(0\);) ``` select build_id , total_working_helpers from builds b ``` [Copy](javascript:void\(0\);) ``` select date(start_time) as date, sum(remote_core_time)/60000 as total_remote_minutesfrom builds bgroup by 1order by 1 ``` [Copy](javascript:void\(0\);) ``` select date(start_time) as date, count(distinct initiator_id) as unique_initiators from builds b group by 1order by 1 ``` [Copy](javascript:void\(0\);) ``` 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 valuesselect 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](javascript:void\(0\);) ``` SELECT date(start_time) as date,count(build_id) as builds from builds where build_status = 'SystemErrorOrUserInterrupt' group by date(start_time) ``` [Copy](javascript:void\(0\);) ``` 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](javascript:void\(0\);) ``` select build_group , count(distinct initiator_id) as unique_initiators from builds b group by 1WITH 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 valuesselect 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](javascript:void\(0\);) ``` 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 valuesselect date(start_time) as date, helper, count(distinct build_id) as buildsfrom (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),helperorder by 1, 3 desc ``` [Copy](javascript:void\(0\);) ``` select initiator_id ,count(distinct initiator_id) as initiatorsfrom builds b group by 1 ``` [Copy](javascript:void\(0\);) ``` 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 [Copy](javascript:void\(0\);) ``` 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_buildsfrom builds b order by 1,2 ``` [Copy](javascript:void\(0\);) ``` 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