Help Center/ CodeArts Req/ API Reference/ API/ Scrum Project Work Items/ Conducting Advanced Query of Work Items

Updated on 2026-10-27 GMT+08:00

Conducting Advanced Query of Work Items

Function

This API is used to query work items based on filter criteria.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account root user has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
codeartsreq:workitem:list	List	-	codeartsreq:Model codeartsreq:ProjectId	-	-

URI

POST /v4/projects/{project_id}/issues

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition A 32-character UUID. It uniquely identifies a project. Obtain a project ID by calling the API for querying projects. The value of project_id in the response message body is a project ID. Constraints A string of 32 characters consisting of letters and digits. Range N/A Default Value N/A

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
subject	No	String	Definition Work item title. Constraints 1 to 200,000 characters. Range N/A Default Value N/A
issue_ids	No	Array of integers	Definition Digital ID of a work item. Constraints A numeric string of 1 to 10 characters. Range 0 to 9999999999 Default Value N/A
assigned_ids	No	Array of strings	Definition Handler ID. You can obtain the digital ID of a user in a specified project using the API for obtaining the user list of a specified project. Constraints ≥ 1 digit Range Min.: 0. Default Value N/A
closed_time_interval	No	String	Definition Work item end duration (start and end time). The value is a Unix timestamp in milliseconds. Examples: 1576114296000 and 1576114396000 Constraints A string of 1 to 13 digits. The first digit ranges from 1 to 9. Use commas (,) to separate values. Range A string of 1 to 13 digits. Default Value N/A
created_time_interval	No	String	Definition Work item creation duration (start and end time). The value is a Unix timestamp in milliseconds. Examples: 1576114296000 and 1576114396000 Constraints A string of 1 to 13 digits. The first digit ranges from 1 to 9. Use commas (,) to separate values. Range A string of 1 to 13 digits. Default Value N/A
creator_ids	No	Array of strings	Definition Creator ID. You can obtain the digital ID of a user in a specified project using the API for obtaining the user list of a specified project. Constraints ≥ 1 digit Range Min.: 0. Default Value N/A
custom_fields	No	Array of custom_fields objects	Definition: Custom fields of a Scrum work item. You can query custom fields of a Scrum work item using the Querying Custom Fields of a Scrum Work Item API. Constraints: N/A Value range: N/A Default value: N/A
developer_ids	No	Array of strings	Definition Developer ID. You can obtain the digital ID of a user in a specified project using the API for obtaining the user list of a specified project. Constraints ≥ 1 digit Range Min.: 0. Default Value N/A
domain_ids	No	Array of integers	Definition Domain ID. The options are as follows: 14: performance 15: performance 16: reliability 17: cyber security 18: maintainability 19: other DFX 20: availability Constraints ≥ 1 digit Range 14, 15, 16, 17, 18, 19, 20 Default Value N/A
done_ratios	No	Array of integers	Definition Work item completion percentage. For example, 20 indicates a completion of 20%. Constraints The value is a number ranging from 0 to 100. Range 0–100 Default Value N/A
include_deleted	No	Boolean	Definition Whether deleted work items are included. Constraints N/A (The allowed values are defined in the range below.) Range true or false Default Value N/A
iteration_ids	No	Array of integers	Definition Sprint ID. You can obtain the sprint list of a project using the Obtaining the Sprint List of a Specified Project API. Constraints ≥ 1 digit Range Min.: 0. Default Value N/A
limit	No	Integer	Definition: Number of advanced work items displayed on each page. Constraints: N/A Options: Minimum value: 1. Maximum value: 100. Default value: 100
module_ids	No	Array of integers	Definition Module ID, which is the value of module_id in the response body returned by the Querying the Project Module List API. Constraints ≥ 1 digit Range Min.: 0. Default Value N/A
offset	No	Integer	Definition Start page number. The value starts from 0 and is an integer multiple of limit. Constraints The value is a string of 0 to 11 digits. If the first digit is 0, the value can only be 0. If the first digit ranges from 1 to 9, the value can contain a maximum of 11 digits. Range Min.: 0. Default Value 0
priority_ids	No	Array of integers	Definition Priority. The options are as follows: 1: low 2: medium 3: high Constraints ≥ 1 digit Range 1, 2, 3 Default Value N/A
severity_ids	No	Array of integers	Definition Severity. The options are as follows: 10: critical 11: major 12: minor 13: info Constraints ≥ 1 digit Range 10, 11, 12, 13 Default Value N/A
status_ids	No	Array of integers	Definition Status ID. Constraints ≥ 1 digit Range 1: new 2: ongoing 3: resolved 4: testing 5: closed 6: rejected Default Value N/A
story_point_ids	No	Array of integers	Definition Story point ID. A story point is an agile method for estimating workloads. It can be regarded as the development cost, which takes into account the required efforts for story delivery, development complexity, and risks. Story point values corresponding to story point IDs: 1: 0 2: 1/2 3: 1 4: 2 5: 3 6: 5 7: 8 8: 13 9: 21 10: 40 11: 80 12: 100 Constraints ≥ 1 digit Range 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 Default Value N/A
tracker_ids	No	Array of integers	Definition Work item type. The options are as follows: 2 (task) 3 (bug) 5 (epic) 6 (feature) 7 (story) Constraints ≥ 1 digit Range 2, 3, 5, 6, 7 Default Value N/A
updated_time_interval	No	String	Definition Work item update duration (start and end time). The value is a Unix timestamp in milliseconds. Examples: 1576114296000 and 1576114396000 Constraints A string of 1 to 13 digits. The first digit ranges from 1 to 9. Use commas (,) to separate values. Range A string of 1 to 13 digits. Default Value N/A

**Table 3** custom_fields
Parameter	Mandatory	Type	Description
custom_field	No	String	Definition: Custom field. You can obtain the custom_field value returned using the [Querying Custom Fields of a Scrum Work Item]ListIssueCustomFields.xml) API. Constraints: This field can be left blank. Value range: N/A Default value: N/A
value	No	String	Definition: Values of custom properties. Use commas (,) to separate multiple values. You can obtain the value by querying the options value returned when calling the Querying Custom Fields of a Scrum Work Item API. Constraints: This field can be left blank. Options: N/A Default value: N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
issues	Array of ListIssueItemResponse objects	Definition: Work item list. Options: N/A
total	Integer	Definition Total. Range ≥ 0

**Table 5** ListIssueItemResponse
Parameter	Type	Description
actual_work_hours	Double	Definition Actual workloads. Range ≥ 0
assigned_cc_user	Array of IssueUser objects	Parameter description: Cc recipient.
assigned_user	IssueUser object	Parameter description: Handler.
begin_time	String	Parameter description: Estimated start time. The format is YYYY-MM-DD. Value range: N/A
closed_time	String	Definition: Closing time. The format is YYYY-MM-DD. Value range: N/A
created_time	String	Parameter description: Creation time. The format is YYYY-MM-DD HH:MM:SS. Value range: N/A
creator	IssueUser object	Parameter description: Creator.
custom_fields	Array of CustomField objects	Parameter description: Custom property value, which is not recommended. Refer to the new_custom_fields field.
developer	IssueUser object	Parameter description: Developer.
domain	domain object	Definition: Domain.
done_ratio	Integer	Definition Work item completion rate. For example, 20 indicates that the completion rate is 20%. Range 0–100
end_time	String	Definition Estimated end time. The format is YYYY-MM-DD. Range N/A
expected_work_hours	Double	Definition Estimated workloads. Range Min.: 0.
id	Integer	Definition Work item ID. Range ≥ 0
iteration	iteration object	Definition Sprint.
module	module object	Definition Module.
name	String	Definition: Title. Options: N/A
new_custom_fields	Array of NewCustomField objects	Definition: Custom property value.
parent_issue	parent_issue object	Definition: Parent work item.
priority	priority object	Definition: Work item priority.
project	IssueProjectResponseV4 object	Definition: Project information.
severity	severity object	Definition: Work item severity.
status	status object	Definition: Work item status.
tracker	tracker object	Definition: Work item type.
updated_time	String	Definition: Update time. The format is YYYY-MM-DD HH:MM:SS. Options: N/A
find_release_dev	String	Definition Version number. Range N/A
release_dev	String	Definition Release version number. Range N/A
env	IssueAttribute object	Definition Environment. Range N/A
tag_list	Array of TagRelation objects	Definition Tag list. Range N/A
deleted	Boolean	Definition: Deleted or not. The options are true (deleted) and false (not deleted). Options: true and false

**Table 6** IssueUser
Parameter	Type	Description
id	Integer	Definition User ID. Range N/A
name	String	Definition Username. Range N/A
nick_name	String	Definition: Alias. Options: N/A
user_id	String	Definition User UUID. Range N/A
user_num_id	Integer	Definition Digital ID of a user. Range N/A
first_name	String	Definition: Username. Value range: N/A

**Table 7** CustomField
Parameter	Type	Description
name	String	Definition: Custom property name. Value range: N/A
new_name	String	Definition: Custom property name. Value range: N/A
value	String	Definition: Value of the custom property. Value range: N/A

**Table 8** domain
Parameter	Type	Description
id	Integer	Definition: Domain ID. The options are as follows: 14: performance 15: performance 16: reliability 17: cyber security 18: maintainability 19: other DFX 20: availability Value range: 14, 15, 16, 17, 18, 19, and 20
name	String	Definition: Domain name. Options: N/A

**Table 9** iteration
Parameter	Type	Description
id	Integer	Definition Sprint ID. Range ≥ 0
name	String	Definition: Sprint name. Options: N/A

**Table 10** module
Parameter	Type	Description
id	Integer	Definition Module ID. Range ≥ 0
name	String	Definition: Module. Options: N/A

**Table 11** NewCustomField
Parameter	Type	Description
custom_field	String	Parameter description: Custom field. You can obtain the custom_field value returned using the [Querying Custom Fields of a Scrum Work Item]ListIssueCustomFields.xml) API.
field_name	String	Definition: Values of custom properties. Use commas (,) to separate multiple values, which can be obtained by querying the name value returned when calling the Querying Custom Fields of a Scrum Work Item API.
value	String	Definition: Values of custom properties. Use commas (,) to separate multiple values. You can obtain the value by querying the options value returned when calling the Querying Custom Fields of a Scrum Work Item API.

**Table 12** parent_issue
Parameter	Type	Description
id	Integer	Definition Parent work item ID. Range Min.: 0.
name	String	Definition: Parent work item. Options: N/A

**Table 13** priority
Parameter	Type	Description
id	Integer	Definition Priority ID. The options are as follows: 1: low 2: medium 3: high Range 1: low 2: medium 3: high
name	String	Definition Priority. Range Low Medium High

**Table 14** IssueProjectResponseV4
Parameter	Type	Description
project_id	String	Definition Project ID. Range N/A
project_name	String	Definition: Project name. Value range: N/A
project_num_id	Integer	Definition Digital ID of a project. Range ≥ 0

**Table 15** severity
Parameter	Type	Description
id	Integer	Definition: Severity ID. The options are as follows: 10: critical 11: major 12: minor 13: info Options: 10, 11, 12, and 13
name	String	Definition: Severity. Options: N/A

**Table 16** status
Parameter	Type	Description
id	Integer	Definition: Status ID. The options are as follows: 1: initial 2: in progress 3: solved 4: testing 5: closed 6: rejected Options: 1, 2, 3, 4, 5, and 6
name	String	Definition: Status name. Options: N/A

**Table 17** tracker
Parameter	Type	Description
id	Integer	Definition: Type ID. The options are as follows: 2 (task) 3 (bug) 5 (epic) 6 (feature) 7 (story) Options: 2, 3, 5, 6, and 7
name	String	Definition: Type name. Options: N/A

**Table 18** IssueAttribute
Parameter	Type	Description
id	Integer	Definition Environment ID. Range N/A
name	String	Definition Environment name. Range N/A

**Table 19** TagRelation
Parameter	Type	Description
relationId	Integer	Definition Association ID. Range N/A
tagId	Integer	Definition Tag ID. Range N/A
region	String	Definition Region. Range N/A
name	String	Definition Tag name. Range N/A

Status code: 400

**Table 20** Response body parameters
Parameter	Type	Description
error_code	String	Definition: Error code. Value range: N/A
error_msg	String	Definition: Error description. Value range: N/A

Status code: 401

**Table 21** Response body parameters
Parameter	Type	Description
error_code	String	Definition: Error code. Value range: N/A
error_msg	String	Definition: Error description. Value range: N/A
request_id	String	Definition Request ID, which is automatically generated by the system. Range N/A

Example Requests

POST https://{endpoint}/v4/projects/526cefde62004de2b62b5e8dd2c2b3af/issues

{
  "status_ids" : [ 1 ]
}

Example Responses

Status code: 200

{
  "issues" : [ {
    "actual_work_hours" : 0,
    "assigned_cc_user" : [ {
      "id" : 4091,
      "name" : "demo_user_name",
      "nick_name" : "Tom"
    } ],
    "assigned_user" : {
      "id" : 4091,
      "name" : "demo_user_name",
      "nick_name" : "Tom"
    },
    "begin_time" : "2020-09-12",
    "created_time" : "2020-09-13 14:40:11",
    "creator" : {
      "id" : 4091,
      "name" : "demo_user_name",
      "nick_name" : "Tom"
    },
    "custom_fields" : [ {
      "name" : "customField16",
      "value" : "Multi-select checkbox",
      "new_name" : "custom_field16"
    } ],
    "new_custom_fields" : [ {
      "custom_field" : "custom_field16",
      "field_name" : "field_name",
      "value" : "Checkbox 1, Checkbox 2"
    } ],
    "developer" : {
      "id" : 4091,
      "name" : "demo_user_name",
      "nick_name" : "Tom"
    },
    "domain" : {
      "id" : 14,
      "name" : "Performance"
    },
    "done_ratio" : 0,
    "end_time" : "2020-09-19",
    "expected_work_hours" : 9,
    "id" : 4567,
    "project" : {
      "project_id" : "526cefde62004de2b62b5e8dd2c2b3af",
      "project_name" : "testDemo",
      "project_num_id" : 78953
    },
    "iteration" : {
      "id" : 456,
      "name" : "Sprint 1"
    },
    "module" : {
      "id" : 456,
      "name" : "Project"
    },
    "name" : "Internationalization improvement",
    "parent_issue" : {
      "id" : 123,
      "name" : "Querying project members"
    },
    "priority" : {
      "id" : 1,
      "name" : "Low"
    },
    "severity" : {
      "id" : 12,
      "name" : "Minor"
    },
    "status" : {
      "id" : 1,
      "name" : "New"
    },
    "tracker" : {
      "id" : 7,
      "name" : "story"
    },
    "updated_time" : "2020-09-14 14:40:11",
    "closed_time" : "2020-09-15 14:40:11",
    "deleted" : false
  } ],
  "total" : 1
}

SDK Sample Code

The SDK sample code is as follows.

Java

     package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.projectman.v4.region.ProjectManRegion;
import com.huaweicloud.sdk.projectman.v4.*;
import com.huaweicloud.sdk.projectman.v4.model.*;

import java.util.List;
import java.util.ArrayList;

public class ListIssuesV4Solution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");

        ICredential auth = new BasicCredentials()
                .withAk(ak)
                .withSk(sk);

        ProjectManClient client = ProjectManClient.newBuilder()
                .withCredential(auth)
                .withRegion(ProjectManRegion.valueOf("<YOUR REGION>"))
                .build();
        ListIssuesV4Request request = new ListIssuesV4Request();
        request.withProjectId("{project_id}");
        ListIssueRequestV4 body = new ListIssueRequestV4();
        List<Integer> listbodyStatusIds = new ArrayList<>();
        listbodyStatusIds.add(1);
        body.withStatusIds(listbodyStatusIds);
        request.withBody(body);
        try {
            ListIssuesV4Response response = client.listIssuesV4(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 
 
  

Python

     # coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkprojectman.v4.region.projectman_region import ProjectManRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkprojectman.v4 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]

    credentials = BasicCredentials(ak, sk)

    client = ProjectManClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(ProjectManRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListIssuesV4Request()
        request.project_id = "{project_id}"
        listStatusIdsbody = [
            1
        ]
        request.body = ListIssueRequestV4(
            status_ids=listStatusIdsbody
        )
        response = client.list_issues_v4(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 
 
  

Go

     package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    projectman "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/projectman/v4"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/projectman/v4/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/projectman/v4/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := projectman.ProjectManClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := projectman.NewProjectManClient(hcClient)

    request := &model.ListIssuesV4Request{}
	request.ProjectId = "{project_id}"
	var listStatusIdsbody = []int32{
        int32(1),
    }
	request.Body = &model.ListIssueRequestV4{
		StatusIds: &listStatusIdsbody,
	}
	response, err := client.ListIssuesV4(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}
 
 
  

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code	Description
200	OK
400	Bad Request
401	Unauthorized

Error Codes

See Error Codes.

Parent topic: Scrum Project Work Items

Previous topic: Querying Work Items of a Project

Next topic: Deleting Scrum Work Items in Batches