Querying Build History in a Specified Period

Function

This API is used to query the history of a build task in a specified period.

Calling Method

For details, see Calling APIs.

URI

GET /v3/jobs/{job_id}/period-history

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
job_id	Yes	String	Definition Enter the ID of the build task whose history you want to query. To obtain this ID, open the build task details page in your browser, and copy the 32-character string, which includes both digits and letters, at the end of the URL. Constraints N/A. Range The value is 32 characters long. Only letters and digits are allowed. Default Value N/A.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
offset	Yes	Integer	Details: Page number, indicating that the query starts from this page. Constraints: N/A Value Range: Only numbers that are 0 or greater can be used.
limit	No	Integer	Details: Number of items displayed on each page. The value of limit is no more than 100. Constraints: N/A Value Range: Only numbers that are 100 or less can be used.
start_time	Yes	String	Details: Start time in the format of "YYYY-MM-DD". Constraints: The time range cannot exceed 30 days. Value Range: The value matches the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$.
end_time	Yes	String	Details: Start time in the format of "YYYY-MM-DD". Constraints: The time range cannot exceed 30 days. Value Range: The value matches the regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. (The value of the X-Subject-Token response header is the user token.) It is obtained by calling the IAM API. Constraints Global tenant tokens are not supported. Use a region-level token whose scope is project. Range N/A. Default Value N/A.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total	Integer	Definition Total number of records. Range 0–2147483647
history_records	Array of history_records objects	Definition A list of build records. Range N/A.

**Table 5** history_records
Parameter	Type	Description
record_id	String	Definition Build record ID. It is a unique key. Range N/A.
job_id	String	Definition Task ID. Range N/A.
build_number	Integer	Definition Build number. Range N/A.
start_time	String	Definition Build start time. Range N/A.
end_time	String	Definition Build end time. Range N/A.
result	String	Definition Build result. Range N/A.
branch	String	Definition Code branch. Range N/A.
commit_id	String	Definition Code commit ID. Range N/A.
commit_message	String	Definition Commit message input by the user. This parameter has a value only when CodeArts Repo repositories are used. Range N/A.
executor	String	Definition Name of the user who runs the build task. Range N/A.
trigger_type	String	Definition Triggering mode. Options include MANUAL (manual execution), TIMED_EXECUTION (schedule), CODEHUB_TRIGGER (code change), or PIPELINE_TRIGGER (pipeline). Range ● MANUAL: Manual trigger ● TIMED_EXECUTION: Scheduled trigger ● CODEHUB_TRIGGER: Code change trigger ● PIPELINE_TRIGGER: Pipeline trigger

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 401

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 403

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 404

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 500

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Requests

GET https://{endpoint}/v3/jobs/{job_id}/period-history?start_time=2021-01-04&end_time=2021-01-14&offset=0&limit=10

Example Responses

Status code: 200

{
  "total" : 1,
  "history_records" : {
    "record_id" : "20201230.1",
    "job_id" : "f9d6c8466d614a9788e9a0acf6c15f46",
    "build_number" : 55,
    "start_time" : "2020-12-30T17:33:11+08:00",
    "end_time" : "2020-12-30T17:33:27+08:00",
    "result" : "FAILURE",
    "branch" : "master",
    "commit_id" : "2f37dd494927d2c6259417c58e5faeb72bfe7150",
    "commit_message" : "test",
    "executor" : "test",
    "trigger_type" : "Manual"
  }
}