Help Center/ Distributed Database Middleware/ API Reference/ APIs (Recommended)/ Task Management/ Querying Tasks (a V3 API)
Updated on 2026-05-30 GMT+08:00
View PDF
Share

Querying Tasks (a V3 API)

Function

This API is used to query tasks.

URI

GET /v3/{project_id}/jobs

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID of a tenant in a region

To obtain this value, see Obtaining a Project ID.
Table 2 Query parameters

Parameter

Mandatory

Type

Description

offset

No

Integer

Index offset.

The query starts from the next piece of data indexed by this parameter. The value is 0 by default.

The value must be a non-negative number.

limit

No

Integer

Maximum records to be queried.

Value range: 1 to 128.

If the parameter value is not specified, 10 records are obtained by default.

start_time

Yes

Long

Query start time in timestamp format, in milliseconds. It cannot be earlier than 30 days prior to the current time.

end_time

Yes

Long

Query end time in timestamp format, in milliseconds.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

offset

Integer

Which page the server starts returning items

limit

Integer

Number of records displayed on each page

total

Integer

Total number

jobs

Array of JobItem objects

Task list
Table 5 JobItem

Parameter

Type

Description

id

String

Task ID

name

String

Task name

status

String

Task execution status

Values:

Running: The task is being executed.

Completed: The task is successfully executed.

Failed: The task fails to be executed.

created_time

String

Creation time in the yyyy-mm-ddThh:mm:ssZ format.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Central European time zone, the offset is +0100.

end_time

String

End time. The format is yyyy-mm-ddThh:mm:ssZ.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Central European time zone, the offset is +0100.

process

String

Task execution progress

The execution progress (such as "60%", indicating the task execution progress is 60%) is displayed only when the task is being executed. Otherwise, "" is returned.

instance_name

String

Instance name

instance_id

String

Instance ID

operations

Array of strings

Operations

database_name

String

Schema name

fail_reason

String

Failure cause

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 500

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Example Request

Querying information about tasks 
GET https://ddm.eu-de.otc.t-systems.com/v3/619d3e78f61b4be68bc5aa0b59edcf7b/jobs?start_time=1746028800000&end_time=1747319097182

Example Response

Status code: 200 
{
  "jobs": [
    {
      "id": "92370d30-3ddc-4e05-b8ab-51662d824318",
      "name": "migrateLogicDb",
      "status": "ToBeSwitched",
      "created_time": "2025-05-20T15:05:13+0000",
      "end_time": "2025-05-20T15:05:13+0000",
      "process": "",
      "instance_name": "UTS-ddm-dtc-src",
      "instance_id": "733c7e8d73a54c27b8308ec784a8be8cin09",
      "operations": [
        "modifySwitchingStrategy",
        "toBeCanceled"
      ],
      "database_name": "db_e487",
      "fail_reason": ""
    },
    {
      "id": "10501cd3-0c19-498b-9ba4-8935ed447542",
      "name": "migrateLogicDb",
      "status": "Completed",
      "created_time": "2025-05-20T14:48:09+0000",
      "end_time": "2025-05-20T15:03:45+0000",
      "process": "",
      "instance_name": "UTS-ddm-dtc-src",
      "instance_id": "733c7e8d73a54c27b8308ec784a8be8cin09",
      "operations": [],
      "database_name": "db_e487",
      "fail_reason": ""
    },
    {
      "id": "57933931-9323-422d-8f3d-20a62eb00c4e",
      "name": "CreateInstance",
      "status": "Completed",
      "created_time": "2025-05-20T07:51:47+0000",
      "end_time": "2025-05-20T07:56:54+0000",
      "process": "",
      "instance_name": "UTS-ddm-dtc-src",
      "instance_id": "733c7e8d73a54c27b8308ec784a8be8cin09",
      "operations": [],
      "database_name": "",
      "fail_reason": ""
    }
  ],
  "offset": 0,
  "limit": 10,
  "total": 3
}

Status code: 400

Bad request

{
  "error_msg" : "Parameter error.",
  "error_code" : "DBS.280001"
}

Status code: 500

Server error

{
  "error_msg" : "Parameter error.",
  "error_code" : "DBS.280001"
}

Status Codes

Status Code

Description

200

OK

400

Bad request

500

Server error

Error Codes

For details, see Error Codes.

Parent topic: Task Management