DescribeProjects

Updated at:
Copy as MD

Queries projects under a tenant in a paginated manner and supports fuzzy search by name or prompt.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

yundun-codesec:DescribeProjects

list

*All Resource

*

None None

Request syntax

GET /v1/projects HTTP/1.1

Request parameters

Parameter

Type

Required

Description

Example

maxResults

integer

No

The maximum number of entries to return per page. Default value: 10. Maximum value: 20.

20

nextToken

string

No

The pagination token. To query the first page, leave this parameter empty or do not specify it. To query the next page, pass the token returned from the previous response without any modifications. If the token in the response is empty, the last page is returned.

eyJ0IjoiMjAyNi0wNy0xNlQwNzo1MzozOC4wMjFaIiwiaSI6MTAwMDQ0OH0

query

string

No

The keyword used for fuzzy search by project name or prompt.

project

sortBy

string

No

The field by which to sort the results. Default value: lastScanTime. Valid values:

  • lastScanTime: The time when the last task was created.

  • createdAt: The time when the project was created.

  • updatedAt: The time when the project was updated.

Valid values:

  • updatedAt
  • createdAt
  • lastScanTime

lastScanTime

sortOrder

string

No

The sort order. Default value: desc. Valid values:

  • desc: Descending order.

  • asc: Ascending order.

Valid values:

  • asc
  • desc

desc

Response elements

Element

Type

Description

Example

object

Schema of Response

requestId

string

The unique identifier of the request.

9A1F403F-0A85-5578-8B7C-55E3E9408659

items

array<object>

The list of projects.

array<object>

The project information.

scanCount

integer

The number of existing non-failed tasks in the project, including queued, running, interactive, and canceled tasks. Failed tasks are not included, and invalid tasks are temporarily included. The value is 0 if no tasks exist.

3

accessType

string

The access method. Valid values: gitlab, jenkins, yunxiao, cli, console, and unknown.

gitlab

sastRisk

object

The SAST risk count. For a project or tenant, the count is based on the current new and recurrent identities. Fixed vulnerabilities are not included, but ignored vulnerabilities are still included. All counts are 0 when no snapshot is available. For the daily task list, the count is based on the actual findings of the task. The disposition buckets are currently 0 and cannot be used to infer the project disposition distribution.

total

integer

The total number of SAST vulnerabilities. For a project or tenant, the current risk is counted by identity. For the daily task list, the count is based on actual findings.

57

bySeverity

object

The severity count mapping. The fixed output includes CRITICAL, HIGH, MEDIUM, LOW, and other. Each bucket is 0 (not null) when no risks are present. After UPPER(TRIM(severity)) is applied, other values are classified into other. The sum of all buckets equals the total number of corresponding risks.

CRITICAL

integer

The non-negative count for the severity bucket. The unit for SAST is vulnerabilities, and the unit for SCA is components with known vulnerabilities.

12

byDisposition

object

The manual disposition distribution. The current risk includes ignored vulnerabilities. The value is 0 when no data is available for each field. For a project or tenant, the count is based on the current identity. For task reports, the count is deduplicated based on the project identity associated with the findings.

pending

integer

The number of project vulnerabilities pending confirmation.

40

confirmed

integer

The number of project vulnerabilities confirmed for remediation.

12

ignored

integer

The number of ignored project vulnerabilities, which are still included in the current risk.

5

scaRisk

object

The risk of SCA components with known vulnerabilities (not the number of CVEs). Each component is counted in a bucket based on its highest severity. For a project or tenant, the latest complete daily SCA statistics are used. The count is 0 and null is not returned when no complete results or snapshots are available.

vulnerableComponentCount

integer

The number of components with known vulnerabilities. The component inventory with vuln_count > 0 takes precedence. If no inventory is available, the count is deduplicated based on the (package_name, version) of the task findings.

4

bySeverity

object

The severity count mapping. The fixed output includes CRITICAL, HIGH, MEDIUM, LOW, and other. Each bucket is 0 (not null) when no risks are present. After UPPER(TRIM(severity)) is applied, other values are classified into other. The sum of all buckets equals the total number of corresponding risks.

HIGH

integer

The non-negative count for the severity bucket. The unit for SAST is vulnerabilities, and the unit for SCA is components with known vulnerabilities.

2

riskSnapshotDate

string

The date (YYYY-MM-DD) in the configured time zone for the latest daily SAST statistics. A value of null indicates that the daily row has not been generated. The risk is 0 for the tenant or project list. For the project overview, if the underlying project identity exists, SAST is displayed immediately and polling continues. Otherwise, 0 and a rescan prompt are displayed for existing projects. This is not the task completion date.

2026-11-13

id

integer

The project ID.

934

name

string

The project name.

manual-hDecBn

description

string

The description.

111

instructionPrompt

string

The natural language prompt provided by the user, which describes the preferences for scanning or result processing, such as ignoring low-risk vulnerabilities.

1111

engines

object

The engine switches in the project or scan snapshot. Only SAST and SCA are supported.

sast

boolean

Specifies whether SAST is supported.

true

sastConfig

object

The SAST engine-level configuration.

remediation

boolean

The component-level remediation suggestions.

sca

boolean

Specifies whether SCA is supported.

true

scaConfig

object

The SCA engine-level configuration.

remediation

boolean

The component-level remediation suggestions.

configRevision

integer

The project configuration version number.

1

source

object

The project source.

type

string

The project type.

manual_upload

createdAt

string

The creation time.

2026-07-28T03:36:31.573Z

updatedAt

string

The update time.

2026-07-28T03:36:31.573Z

createdBy

string

The user ID of the project creator.

11111

lastScanTime

string

The time when the last task was created.

2026-07-28T03:36:31.573Z

totalCount

integer

The total number of entries.

2

maxResults

integer

The page size.

Note

If this parameter is not specified, all projects are displayed.

10

nextToken

string

The pagination token. An empty value indicates the last page.

eyJ0IjoiMjAyNi0wNy0xNlQwNzo1MzozOC4wMjFaIiwiaSI6MTAwMDQ0OH0

Examples

Success response

JSON format

{
  "requestId": "9A1F403F-0A85-5578-8B7C-55E3E9408659",
  "items": [
    {
      "scanCount": 3,
      "accessType": "gitlab",
      "sastRisk": {
        "total": 57,
        "bySeverity": {
          "key": 12
        },
        "byDisposition": {
          "pending": 40,
          "confirmed": 12,
          "ignored": 5
        }
      },
      "scaRisk": {
        "vulnerableComponentCount": 4,
        "bySeverity": {
          "key": 2
        }
      },
      "riskSnapshotDate": "2026-11-13",
      "id": 934,
      "name": "manual-hDecBn",
      "description": "111",
      "instructionPrompt": "1111",
      "engines": {
        "sast": true,
        "sastConfig": {
          "remediation": false
        },
        "sca": true,
        "scaConfig": {
          "remediation": false
        }
      },
      "configRevision": 1,
      "source": {
        "type": "manual_upload"
      },
      "createdAt": "2026-07-28T03:36:31.573Z",
      "updatedAt": "2026-07-28T03:36:31.573Z",
      "createdBy": "11111",
      "lastScanTime": "2026-07-28T03:36:31.573Z"
    }
  ],
  "totalCount": 2,
  "maxResults": 10,
  "nextToken": "eyJ0IjoiMjAyNi0wNy0xNlQwNzo1MzozOC4wMjFaIiwiaSI6MTAwMDQ0OH0"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter.%s Invalid parameter:%s. Invalid parameter:%s.
400 NotFound.%s The resource does not exist. The resource does not exist.
503 ServiceUnavailable.%s Finding snapshot API is disabled (FindingSnapshotDisabled); omit accessType to use the legacy project list.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.