All Products
Search

This Product

    Cloud Parallel File Storage:DescribeFilesets

    Document Center

    Cloud Parallel File Storage:DescribeFilesets

    Last Updated:Aug 13, 2026

    Queries the list of created filesets.

    Operation description

    • Only CPFS 2.2.0 and later and CPFS for Lingjun 2.7.0 and later support filesets. You can view the version information on the file system details page in the console.

    • For filter keys (Filters), FsetIds requires an exact match, while FileSystemPath and Description support fuzzy match.

    • Combination queries are supported.

    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

    nas:DescribeFilesets

    list

    *FileSystem

    acs:nas:{#regionId}:{#accountId}:filesystem/{#FileSystemId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    FileSystemId

    string

    Yes

    The file system ID.

    • CPFS: The ID must start with cpfs-, such as cpfs-099394bd928c****.

    • CPFS for Lingjun: The ID must start with bmcpfs-, such as bmcpfs-290w65p03ok64ya****.

    Note

    This operation supports only CPFS file systems (with ID prefixes cpfs-* or bmcpfs-*). General-purpose NAS and Extreme NAS file systems are not supported.

    bmcpfs-290w65p03ok64ya****
    Filters

    array<object>

    No

    The filter key information for the filesets to query.

    object

    No

    Key

    string

    No

    The name of the filter key. Valid values:

    • FsetIds: filters by fileset ID.

    • FileSystemPath: filters by the path of the fileset in the CPFS file system.

    • Description: filters by the description of the fileset.

    • QuotaExists: filters by whether a quota exists.

    Note

    Only CPFS for Lingjun 2.7.0 and later support filtering by the QuotaExists parameter.

    Valid values:

    • FileSystemPath :

      filters by the path of the fileset in the CPFS file system.

    • Description :

      filters by the description of the fileset.

    • FsetIds :

      filters by fileset ID.

    • QuotaExists :

      filters by whether a quota exists.

    FsetIds
    Value

    string

    No

    The value of the filter key. Wildcards are not supported for this parameter.

    • If Key is set to FsetIds, Value is set to a fileset ID. You can specify one or more fileset IDs, up to a maximum of 10. Separate multiple values with commas (,). Example: fset-1902718ea0ae**** or fset-1902718ea0ae****,fset-3212718ea0ae****.

    • If Key is set to FileSystemPath, Value is set to the path or a partial path of the fileset in the CPFS file system. The value must be 2 to 1,024 characters in length and encoded in UTF-8.

    • If Key is set to Description, Value is set to the description or a partial description of the fileset.

    • If Key is set to QuotaExists, Value is set to true or false. If this parameter is left empty, all filesets are returned.

    fset-1902718ea0ae****
    NextToken

    string

    No

    The pagination token that is used in the next request to retrieve a new page of results. If the return results are truncated, use NextToken to initiate a new request to retrieve the content after the truncation point.

    TGlzdFJlc291cmNlU****mVzJjE1MTI2NjY4NzY5MTAzOTEmMiZORnI4NDhVeEtrUT0=
    MaxResults

    integer

    No

    The number of results for each query.

    Valid values: 10 to 100. Default value: 20.

    20
    OrderByField

    string

    No

    The field used for sorting.

    • FileCountLimit: the quota file count limit.

    • SizeLimit: the quota capacity limit.

    • FileCountUsage: the file count usage.

    • SpaceUsage: the capacity usage.

    Valid values:

    • SpaceUsage :

      capacity usage.

    • FileCountLimit :

      quota file count limit.

    • SizeLimit :

      quota capacity limit.

    • FileCountUsage :

      file count usage.

    FileCountLimit
    SortOrder

    string

    No

    The sort order.

    • asc (default): ascending order, which sorts results from smallest to largest.

    • desc: descending order, which sorts results from largest to smallest.

    Note

    This field takes effect only when the OrderByField parameter is specified.

    Valid values:

    • asc :

      ascending order.

    • desc :

      descending order.

    asc

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID.

    2D69A58F-345C-4FDE-88E4-BF518948****
    NextToken

    string

    The pagination token that is used in the next request to retrieve a new page of results. If the return results are truncated, use NextToken to initiate a new request to retrieve the content after the truncation point.

    TGlzdFJlc291cmNlU****mVzJjE1MTI2NjY4NzY5MTAzOTEmMiZORnI4NDhVeEtrUT0=
    FileSystemId deprecated

    string

    The file system ID.

    • CPFS: The ID starts with cpfs-, such as cpfs-099394bd928c****.

    • CPFS for Lingjun: The ID starts with bmcpfs-, such as bmcpfs-290w65p03ok64ya****.

    bmcpfs-290w65p03ok64ya****
    Entries

    object

    Entrie

    array<object>

    The collection of fileset information.

    array<object>

    The file information collection.

    Description

    string

    The description of the fileset.

    test
    FileSystemPath

    string

    The path of the fileset.

    pathtoroot/fset
    FsetId

    string

    Fileset ID。

    fset-1902718ea0ae****
    Status

    string

    The status of the fileset. Valid values:

    • CREATING: The fileset is being created.

    • CREATED: The fileset has been created and is running normally.

    • RELEASING: The fileset is being released.

    • RELEASED: The fileset has been deleted.

    CREATED
    CreateTime

    string

    The time when the fileset was created.

    The time follows the ISO 8601 standard in the format: yyyy-MM-ddTHH:mm:ssZ.

    2021-09-30T10:08:08Z
    UpdateTime

    string

    The time when the fileset was last updated.

    The time follows the ISO 8601 standard in the format: yyyy-MM-ddTHH:mm:ssZ.

    2021-09-30T10:08:08Z
    DeletionProtection

    boolean

    The release protection property of the instance. Specifies whether the instance can be released from the console or by calling the DeleteFileset operation.

    • true: Release protection is enabled.

    • false: Release protection is disabled.

    Note

    This property only restricts manual release operations and does not apply to system-initiated release operations.

    true
    FileCountUsage

    integer

    The file count usage.

    Note

    Only CPFS for Lingjun 2.7.0 and later support this parameter.

    1024
    SpaceUsage

    integer

    The capacity usage. Unit: bytes.

    Note

    Only CPFS for Lingjun 2.7.0 and later support this parameter.

    1024
    Quota

    object

    The quota information.

    Note

    Only CPFS for Lingjun 2.7.0 and later support this parameter.

    SizeLimit

    integer

    The quota capacity limit. Unit: bytes.

    • Minimum value: 10,737,418,240 (10 GiB).

    • Increment: 1,073,741,824 (1 GiB).

    10737418240
    FileCountLimit

    integer

    The quota file count limit. Valid values:

    • Minimum value: 10,000.

    • Maximum value: 10,000,000,000.

    10000
    FileSystemId

    string

    The file system ID.

    • CPFS: The ID starts with cpfs-, such as cpfs-099394bd928c****.

    • CPFS for Lingjun: The ID starts with bmcpfs-, such as bmcpfs-290w65p03ok64ya****.

    bmcpfs-290w65p03ok64ya****

    Examples

    Success response

    JSON format

    {
  "RequestId": "2D69A58F-345C-4FDE-88E4-BF518948****",
  "NextToken": "TGlzdFJlc291cmNlU****mVzJjE1MTI2NjY4NzY5MTAzOTEmMiZORnI4NDhVeEtrUT0=",
  "FileSystemId": "bmcpfs-290w65p03ok64ya****",
  "Entries": {
    "Entrie": [
      {
        "Description": "test",
        "FileSystemPath": "pathtoroot/fset",
        "FsetId": "fset-1902718ea0ae****",
        "Status": "CREATED",
        "CreateTime": "2021-09-30T10:08:08Z",
        "UpdateTime": "2021-09-30T10:08:08Z",
        "DeletionProtection": true,
        "FileCountUsage": 1024,
        "SpaceUsage": 1024,
        "Quota": {
          "SizeLimit": 10737418240,
          "FileCountLimit": 10000
        },
        "FileSystemId": "bmcpfs-290w65p03ok64ya****"
      }
    ]
  }
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 IllegalCharacters The parameter contains illegal characters. The parameter contains illegal characters.
    400 MissingFileSystemId FileSystemId is mandatory for this action. The FileSystemId parameter is not specified.
    400 InvalidParameter.SortOrder Invalid sort order. Parameter SortOrder error.
    400 InvalidParameter.SortOrderField Invalid sort order field. Parameter SortOrderField error.
    400 InvalidFilesystemType.NotSupport The API operation does not support the file system type. The API operation does not support the file system type.
    403 OperationDenied.FilesetNotSupported The operation is not supported. The file system does not support Fileset.
    404 InvalidFileSystem.NotFound The specified file system does not exist. The specified file system does not exist.
    404 InvalidFilterParam The specified Filter.N.Key is invalid. The specified Filter.N.Key parameter is invalid.
    404 InvalidFilterValue The specified Filter.N.Value is invalid. The specified Filter.N.Value parameter is invalid.
    404 InvalidParameter.InvalidNextToken The specified NextToken is invaild.
    404 InvalidParameter.InvalidMaxResults The specified MaxResults is invalid. The specified MaxResults is invalid.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.