Help Center/ Scalable File Service/ API Reference/ SFS Turbo APIs/ File System Management/ Listing Asynchronous Tasks of a File System
Updated on 2025-04-28 GMT+08:00
View PDF
Share

Listing Asynchronous Tasks of a File System

Function

This API is used to list the asynchronous tasks of a file system. Only tasks for querying the directory usage can be listed. Such tasks are also referred to as DU tasks. The value of feature in the API request path is dir-usage.

Constraints

This API is only supported for file systems created after August 1, 2023. The obtained data may not be the latest as there is a 5-minute delay between the frontend and background. The value of feature in the API request path can only be the following:

  • dir-usage

This API is only supported for the following types of file systems:

  • 20 MB/s/TiB

  • 40 MB/s/TiB

  • 125 MB/s/TiB

  • 250 MB/s/TiB

  • 500 MB/s/TiB

  • 1,000 MB/s/TiB

For SFS Turbo Standard, Standard-Enhanced, Performance, Performance-Enhanced file systems, use the API for querying the file system directory usage.

URI

GET /v1/{project_id}/sfs-turbo/shares/{share_id}/fs/{feature}/tasks

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

The project ID.

share_id

Yes

String

The file system ID.

feature

Yes

String

The task type. For example, the value for DU tasks is dir-usage.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

marker

No

String

The marker. The value is the same as task_id.

limit

No

Integer

The limit. The value must be a positive integer. The default value is 20 and the maximum value is 100.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

The account token.

Content-Type

Yes

String

The MIME type, which can be application or json.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

tasks

Array of OneFsTaskResp objects

The task list.
Table 5 OneFsTaskResp

Parameter

Type

Description

task_id

String

The task ID.

status

String

The task status, which can be SUCCESS, DOING, or FAIL.

Enumeration values:

  • SUCCESS

  • DOING

  • FAIL

dir_usage

FsDuInfo object

The resource usages of a directory (subdirectories included).

begin_time

String

The task start time in UTC format, for example, 2006-01-02 15:04:05.

end_time

String

The task end time in UTC format, for example, 2006-01-02 15:04:06.
Table 6 FsDuInfo

Parameter

Type

Description

path

String

The valid full path of a directory in the file system.

used_capacity

Long

The used capacity, in bytes.

file_count

FsFileCount object

The total number of files in this directory.

message

String

The error message.
Table 7 FsFileCount

Parameter

Type

Description

dir

Long

The number of directories.

regular

Long

The number of regular files.

pipe

Long

The number of pipe files.

char

Long

The number of character devices.

block

Long

The number of block devices.

socket

Long

The number of sockets.

symlink

Long

The number of symbolic links.

Status code: 400

Table 8 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 9 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Status code: 404

Table 10 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 11 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Status code: 500

Table 12 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 13 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Example Requests

Listing 50 DU tasks starting from the task whose ID is 11abef677ac40f46644d1d5cfc2424a4 for the file system whose ID is 77ba6f4b-6365-4895-8dda-bc7142af4dde

GET HTTPS://{endpoint}/v1/{project_id}/sfs-turbo/shares/77ba6f4b-6365-4895-8dda-bc7142af4dde/fs/dir-usage/tasks?marker=11abef677ac40f46644d1d5cfc2424a4&limit=50

Example Responses

Status code: 200

Success

{
  "tasks" : [ {
    "task_id" : "2b31ed520xxxxxxebedb6e57xxxxxxxx",
    "status" : "SUCCESS",
    "dir_usage" : {
      "path" : "/path",
      "used_capacity" : 0,
      "file_count" : {
        "dir" : 0,
        "regular" : 0,
        "pipe" : 0,
        "char" : 0,
        "block" : 0,
        "socket" : 0,
        "symlink" : 0
      },
      "message" : ""
    },
    "begin_time" : "2023-03-01 11:46:01",
    "end_time" : "2023-03-01 11:46:01"
  } ]
}

Status code: 400

Error response

{
  "errCode" : "SFS.TURBO.0123",
  "errMsg" : "feature invalid"
}

Status code: 404

Error response

{
  "errCode" : "SFS.TURBO.0124",
  "errMsg" : "task_id not found"
}

Status code: 500

Error response

{
  "errCode" : "SFS.TURBO.0005",
  "errMsg" : "Internal server error"
}

Status Codes

Status Code

Description

200

Success

400

Error response

404

Error response

500

Error response

Error Codes

See Error Codes.

Parent topic: File System Management