Help Center/Data Replication Service/API Reference/APIs V5.0 (in OBT)/Task Management/Querying Tasks

Updated on 2026-03-17 GMT+08:00

Querying Tasks

Function

This API is used to query tenant tasks by enterprise project, engine type, network type, task status, task name, or task ID.

Constraints

This API is available only for synchronization from MySQL to MySQL, migration from Redis to GeminiDB Redis, migration from Redis Cluster to GeminiDB Redis, and synchronization from Oracle to GaussDB Distributed.
This API can be used only in certain regions. For details, see Endpoints.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permissions are required for calling this API.

URI

GET /v5/{project_id}/jobs

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID.

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
job_type	Yes	String	Task scenario. Values: migration: real-time migration. sync: real-time synchronization. cloudDataGuard: real-time disaster recovery. Enumerated values: migration sync cloudDataGuard
name	No	String	Task ID or name. You can enter a maximum of 10 task IDs separated by commas (,).
status	No	String	Task status. Values: CREATING: The task is being created. CREATE_FAILED: The task fails to be created. CONFIGURATION: The task is being configured. STARTJOBING: The task is being started. WAITING_FOR_START: The task is waiting to be started. START_JOB_FAILED: The task fails to be started. FULL_TRANSFER_STARTED: Full migration is in progress, and the initialization is in progress in the DR scenario. FULL_TRANSFER_FAILED: Full migration fails, and the initialization fails in the DR scenario. FULL_TRANSFER_COMPLETE: Full migration is complete, and the initialization is complete in the DR scenario. INCRE_TRANSFER_STARTED: Incremental migration is in progress, and the disaster recovery is in progress in the DR scenario. INCRE_TRANSFER_FAILED: Incremental migration fails, and a DR exception occurs. RELEASE_RESOURCE_STARTED: The task is being stopped. RELEASE_RESOURCE_FAILED: The task fails to be stopped. RELEASE_RESOURCE_COMPLETE: The task is stopped. CHANGE_JOB_STARTED: The task is being changed. CHANGE_JOB_FAILED: The task fails to be changed. CHILD_TRANSFER_STARTING: The subtask is being started. CHILD_TRANSFER_STARTED: The subtask is being migrated. CHILD_TRANSFER_COMPLETE: The subtask migration is complete. CHILD_TRANSFER_FAILED: The subtask fails to be migrated. RELEASE_CHILD_TRANSFER_STARTED: The subtask is being stopped. RELEASE_CHILD_TRANSFER_COMPLETE: The subtask is stopped. You can query an abnormal task separately or query all abnormal tasks in the following states: CREATE_FAILED, START_JOB_FAILED, FULL_TRANSFER_FAILED, INCRE_TRANSFER_FAILED, RELEASE_RESOURCE_FAILED, CHANGE_JOB_FAILED and CHILD_TRANSFER_FAILED. Enumerated values: CREATING CREATE_FAILED CONFIGURATION STARTJOBING WAITING_FOR_START START_JOB_FAILED FULL_TRANSFER_STARTED FULL_TRANSFER_FAILED FULL_TRANSFER_COMPLETE INCRE_TRANSFER_STARTED INCRE_TRANSFER_FAILED RELEASE_RESOURCE_STARTED RELEASE_RESOURCE_FAILED RELEASE_RESOURCE_COMPLETE CHANGE_JOB_STARTED CHANGE_JOB_FAILED CHILD_TRANSFER_STARTING CHILD_TRANSFER_STARTED CHILD_TRANSFER_COMPLETE CHILD_TRANSFER_FAILED RELEASE_CHILD_TRANSFER_STARTED RELEASE_CHILD_TRANSFER_COMPLETE
engine_type	No	String	Engine type. Values: oracle-to-gaussdbv5: Synchronization from Oracle to GaussDB distributed. redis-to-gaussredis: Migration from Redis to GeminiDB Redis. rediscluster-to-gaussredis: Migration from Redis Cluster to GeminiDB Redis. Enumerated values: oracle-to-gaussdbv5 redis-to-gaussredis rediscluster-to-gaussredis
net_type	No	String	Network type. Values: eip: public network. vpc: VPC network. vpn: VPN or Direct Connect. Enumerated values: eip vpc vpn
enterprise_project_id	No	String	Enterprise project ID. Default value: "", indicating that tasks in all enterprise projects are queried.
offset	No	Integer	Offset. The records after this offset will be queried.
limit	No	Integer	Maximum number of records that can be returned.
sort_key	No	String	The keyword based on which the returned results are sorted. The default value is create_time. The following keywords are supported: name status create_time net_type job_direction pay_mode
sort_dir	No	String	Result sorting order. The value can be desc (descending order) or asc (ascending order). The default value is desc.
instance_ids	No	Array of strings	List of database instance IDs. The default value is null, indicating that database instance IDs are not used for task filtering.
instance_ip	No	String	IP address of the database instance bound to the DRS. The default value is "", indicating that the IP address of the database instance bound to the DRS is not used for task filtering.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	MIME type of the request body. Use the default value application/json. For APIs used to upload objects or images, the value varies depending on the flow type. The default value is application/json.
X-Auth-Token	Yes	String	User token obtained from IAM. It is a response to the API for obtaining a user token. This API is the only one that does not require authentication. After a request is processed, the value of X-Subject-Token in the header is the token value.
X-Language	No	String	Request language type. Default value: en-us Enumerated values: en-us zh-cn

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total_count	Integer	Total number of tasks in the list, which is irrelevant to pagination.
jobs	Array of objects	Task details. For details, see Table 5.

**Table 5** Data structure description of field **jobs**
Parameter	Type	Description
id	String	Task ID.
name	String	Task name.
status	String	Task status. Values: CREATING: The task is being created. CREATE_FAILED: The task fails to be created. CONFIGURATION: The task is being configured. STARTJOBING: The task is being started. WAITING_FOR_START: The task is waiting to be started. START_JOB_FAILED: The task fails to be started. FULL_TRANSFER_STARTED: Full migration is in progress, and the initialization is in progress in the DR scenario. FULL_TRANSFER_FAILED: Full migration fails, and the initialization fails in the DR scenario. FULL_TRANSFER_COMPLETE: Full migration is complete, and the initialization is complete in the DR scenario. INCRE_TRANSFER_STARTED: Incremental migration is in progress, and the disaster recovery is in progress in the DR scenario. INCRE_TRANSFER_FAILED: Incremental migration fails, and a DR exception occurs. RELEASE_RESOURCE_STARTED: The task is being stopped. RELEASE_RESOURCE_FAILED: The task fails to be stopped. RELEASE_RESOURCE_COMPLETE: The task is stopped. CHANGE_JOB_STARTED: The task is being changed. CHANGE_JOB_FAILED: The task fails to be changed. CHILD_TRANSFER_STARTING: The subtask is being started. CHILD_TRANSFER_STARTED: The subtask is being migrated. CHILD_TRANSFER_COMPLETE: The subtask migration is complete. CHILD_TRANSFER_FAILED: The subtask fails to be migrated. RELEASE_CHILD_TRANSFER_STARTED: The subtask is being stopped. RELEASE_CHILD_TRANSFER_COMPLETE: The subtask is stopped. Enumerated values: CREATING CREATE_FAILED CONFIGURATION STARTJOBING WAITING_FOR_START START_JOB_FAILED FULL_TRANSFER_STARTED FULL_TRANSFER_FAILED FULL_TRANSFER_COMPLETE INCRE_TRANSFER_STARTED INCRE_TRANSFER_FAILED RELEASE_RESOURCE_STARTED RELEASE_RESOURCE_FAILED RELEASE_RESOURCE_COMPLETE CHANGE_JOB_STARTED CHANGE_JOB_FAILED CHILD_TRANSFER_STARTING CHILD_TRANSFER_STARTED CHILD_TRANSFER_COMPLETE CHILD_TRANSFER_FAILED RELEASE_CHILD_TRANSFER_STARTED RELEASE_CHILD_TRANSFER_COMPLETE
description	String	Task description.
create_time	String	Task creation time.
engine_type	String	Engine type. The value can be: oracle-to-gaussdbv5: Synchronization from Oracle to GaussDB distributed. redis-to-gaussredis: Migration from Redis to GeminiDB Redis. rediscluster-to-gaussredis: Migration from Redis Cluster to GeminiDB Redis. Enumerated values: oracle-to-gaussdbv5 redis-to-gaussredis rediscluster-to-gaussredis
net_type	String	Network type. Values: eip: public network. vpc: VPC network. The VPC network cannot be selected in DR scenarios. vpn: VPN or Direct Connect. Enumerated values: eip vpc vpn
charging_mode	String	Billing mode. Values: period: indicates the yearly/monthly billing. on_demand: indicates the pay-per-use billing. Enumerated values: period on_demand
billing_tag	Boolean	Whether to support billing.
job_direction	String	Task direction. Values: up: to-the-cloud scenarios and DR scenarios where the current cloud is the standby. down: out-of-cloud scenarios and DR scenarios where the current cloud is the active. non-dbs: self-built databases. Enumerated values: up down non-dbs
job_type	String	Task scenario. Values: migration: real-time migration. sync: real-time synchronization. cloudDataGuard: real-time disaster recovery. Enumerated values: migration sync cloudDataGuard
task_type	String	Migration type. Values: FULL_TRANS: full migration. FULL_INCR_TRANS: full+incremental migration. INCR_TRANS: incremental migration. Enumerated values: FULL_TRANS FULL_INCR_TRANS INCR_TRANS
enterprise_project_id	String	Enterprise project ID.
job_mode	String	Task mode. Values: single: indicates a single task. sync_child: indicates a subtask to be synchronized. multi_to_single: indicates a many-to-one task. Enumerated values: single sync_child multi_to_single
job_mode_role	String	Task role. Values: parent: indicates a parent task. child: indicates a subtask. master: indicates a primary task. slave: indicates a standby task. Enumerated values: parent child master slave
is_multi_az	Boolean	Whether the task is a primary/standby task.
node_role	String	Node role.
node_new_framework	Boolean	Whether the framework is a new framework.
job_action	Object	The set of task operation commands. For details, see Table 7.
children	Array of objects	Information body of a subtask list. For details, see Table 6.

**Table 6** Data structure description of field **children**
Parameter	Type	Description
id	String	Task ID.
name	String	Task name.
status	String	Task status. Values: CREATING: The task is being created. CREATE_FAILED: The task fails to be created. CONFIGURATION: The task is being configured. STARTJOBING: The task is being started. WAITING_FOR_START: The task is waiting to be started. START_JOB_FAILED: The task fails to be started. FULL_TRANSFER_STARTED: Full migration is in progress, and the initialization is in progress in the DR scenario. FULL_TRANSFER_FAILED: Full migration fails, and the initialization fails in the DR scenario. FULL_TRANSFER_COMPLETE: Full migration is complete, and the initialization is complete in the DR scenario. INCRE_TRANSFER_STARTED: Incremental migration is in progress, and the disaster recovery is in progress in the DR scenario. INCRE_TRANSFER_FAILED: Incremental migration fails, and a DR exception occurs. RELEASE_RESOURCE_STARTED: The task is being stopped. RELEASE_RESOURCE_FAILED: The task fails to be stopped. RELEASE_RESOURCE_COMPLETE: The task is stopped. CHANGE_JOB_STARTED: The task is being changed. CHANGE_JOB_FAILED: The task fails to be changed. CHILD_TRANSFER_STARTING: The subtask is being started. CHILD_TRANSFER_STARTED: The subtask is being migrated. CHILD_TRANSFER_COMPLETE: The subtask migration is complete. CHILD_TRANSFER_FAILED: The subtask fails to be migrated. RELEASE_CHILD_TRANSFER_STARTED: The subtask is being stopped. RELEASE_CHILD_TRANSFER_COMPLETE: The subtask is stopped. Enumerated values: CREATING CREATE_FAILED CONFIGURATION STARTJOBING WAITING_FOR_START START_JOB_FAILED FULL_TRANSFER_STARTED FULL_TRANSFER_FAILED FULL_TRANSFER_COMPLETE INCRE_TRANSFER_STARTED INCRE_TRANSFER_FAILED RELEASE_RESOURCE_STARTED RELEASE_RESOURCE_FAILED RELEASE_RESOURCE_COMPLETE CHANGE_JOB_STARTED CHANGE_JOB_FAILED CHILD_TRANSFER_STARTING CHILD_TRANSFER_STARTED CHILD_TRANSFER_COMPLETE CHILD_TRANSFER_FAILED RELEASE_CHILD_TRANSFER_STARTED RELEASE_CHILD_TRANSFER_COMPLETE
description	String	Task description.
create_time	String	Task creation time.
engine_type	String	Engine type. The value can be: oracle-to-gaussdbv5: Synchronization from Oracle to GaussDB distributed. redis-to-gaussredis: Migration from Redis to GeminiDB Redis. rediscluster-to-gaussredis: Migration from Redis Cluster to GeminiDB Redis. Enumerated values: oracle-to-gaussdbv5 redis-to-gaussredis rediscluster-to-gaussredis
net_type	String	Network type. Values: eip: public network. vpc: VPC network. The VPC network cannot be selected in DR scenarios. vpn: VPN or Direct Connect. Enumerated values: eip vpc vpn
charging_mode	String	Billing mode. Values: period: indicates the yearly/monthly billing. on_demand: indicates the pay-per-use billing. Enumerated values: period on_demand
billing_tag	Boolean	Whether to support billing.
job_direction	String	Task direction. Values: up: to-the-cloud scenarios and DR scenarios where the current cloud is the standby. down: out-of-cloud scenarios and DR scenarios where the current cloud is the active. non-dbs: self-built databases. Enumerated values: up down non-dbs
job_type	String	Task scenario. Values: migration: real-time migration. sync: real-time synchronization. cloudDataGuard: real-time disaster recovery. Enumerated values: migration sync cloudDataGuard
task_type	String	Task mode. Values: FULL_TRANS: full migration. FULL_INCR_TRANS: full+incremental migration. INCR_TRANS: incremental migration. Enumerated values: FULL_TRANS FULL_INCR_TRANS INCR_TRANS
enterprise_project_id	String	Enterprise project ID.
job_mode	String	Task mode. Values: single: indicates a single task. sync_child: indicates a subtask to be synchronized. multi_to_single: indicates a many-to-one task. Enumerated values: single sync_child multi_to_single
job_mode_role	String	Task role. Values: parent: indicates a parent task. child: indicates a subtask. master: indicates a primary task. slave: indicates a standby task. Enumerated values: parent child master slave
is_multi_az	Boolean	Whether the task is a primary/standby task.
node_role	String	Node role.
node_new_framework	Boolean	Whether the framework is a new framework.
job_action	Object	The set of task operation commands. For details, see Table 7.

**Table 7** Data structure description of field **job_action**
Parameter	Type	Description
available_actions	Array of strings	The set of operation commands that can be executed for a task.
unavailable_actions	Array of strings	The set of operation commands that cannot be executed for a task.
current_action	String	Current operation command of a task. Values: API_CONFIGURATION_ACTION: indicates the operation command for calling an open API of a task. CHANGE: indicates the operation command for modifying a task. CHANGE_MODE: indicates the operation command for changing the task mode. CHOOSE_OBJECT: indicates the operation command for selecting an object. CLONE: indicates the operation command for cloning a task. CONTINUE_APPLY: indicates the operation command for starting workload replay. This parameter is available for synchronization from Oracle to GaussDB Distributed. CONTINUE_CAPTURE: indicates the operation command for starting workload capture. This parameter is available for synchronization from Oracle to GaussDB Distributed. CONTINUE_JOB: indicates the operation command for resuming a failed or stopped task. This parameter is available for synchronization from Oracle to GaussDB Distributed. CREATE: indicates the operation command for creating a task. DELETE: indicates the operation command for deleting a task. FREE_RESOURCE: indicates the operation command for releasing resources. JUMP_RETRY: indicates the operation command for skipping a resumable task. MODIFY_CONFIGURATION: indicates the operation command for modifying task configurations. MODIFY_DB_CONFIG: indicates the operation command for modifying database configurations. MODIFY_TASK_NUMBER: indicates the operation command for modifying the number of threads. NODE_FLAVOR_MODIFY: indicates the operation command for changing node specifications. ORDER_INFO: indicates the operation command for querying order details. PAUSE: indicates the operation command for pausing a task. PAY_ORDER: indicates the operation command for paying a yearly/monthly order. PRE_CHECK: indicates the operation command for performing a pre-check. QUERY_PRE_CHECK: indicates the operation command for querying the precheck result. RESET: indicates the operation command for resetting a task. RESET_DB_PWD: indicates the operation command for resetting the password of the source or destination database. RETRY: indicates the operation command for retrying a task. START: indicates the operation command for starting a task. START_INCR: indicates the operation command for starting an incremental task. STOP_APPLY: indicates the operation command for stopping workload replay. This parameter is available for synchronization from Oracle to GaussDB Distributed. STOP_CAPTURE: indicates the operation command for stopping workload capture. This parameter is available for synchronization from Oracle to GaussDB Distributed. STOP_JOB: indicates the operation command for stopping a task. This parameter is available for synchronization from Oracle to GaussDB Distributed. SWITCH_OVER: indicates the operation command for performing a DR switchover. TO_PERIOD: indicates the operation command for changing the billing mode to yearly/monthly. TO_RENEW: indicates the operation command for renewing a yearly/monthly task. UNSUBSCRIBE: indicates the operation command for unsubscribing from a yearly/monthly task. Enumerated values: API_CONFIGURATION_ACTION CHANGE CHANGE_MODE CHOOSE_OBJECT CLONE CONTINUE_APPLY CONTINUE_CAPTURE CONTINUE_JOB CREATE DELETE FREE_RESOURCE JUMP_RETRY MODIFY_CONFIGURATION MODIFY_DB_CONFIG MODIFY_TASK_NUMBER NODE_FLAVOR_MODIFY ORDER_INFO PAUSE PAY_ORDER PRE_CHECK QUERY_PRE_CHECK RESET RESET_DB_PWD RETRY START START_INCR STOP_APPLY STOP_CAPTURE STOP_JOB SWITCH_OVER TO_PERIOD TO_RENEW UNSUBSCRIBE

Status code: 400

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Error code. Minimum length: 12 Maximum length: 12
error_msg	String	Error message. Minimum length: 1 Maximum length: 512

Example Request

Querying the real-time DR task list

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs?job_type=cloudDataGuard&name=&status=&engine_type=&net_type=&enterprise_project_id=&offset=0&limit=10&sort_key=create_time&sort_dir=desc

Querying the real-time migration task list

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs?job_type=migration&name=&status=&engine_type=&net_type=&enterprise_project_id=&offset=0&limit=10&sort_key=create_time&sort_dir=desc

Querying the real-time synchronization task list

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs?job_type=sync&name=&status=&engine_type=&net_type=&enterprise_project_id=&offset=0&limit=10&sort_key=create_time&sort_dir=desc

Querying the real-time DR task list based on the database IP address

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs?job_type=cloudDataGuard&name=&status=&engine_type=&net_type=&enterprise_project_id=&offset=0&limit=10&sort_key=create_time&sort_dir=desc&instance_ip=127.0.0.1

Querying the real-time DR task list based on the database ID

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs?job_type=cloudDataGuard&name=&status=&engine_type=&net_type=&enterprise_project_id=&offset=0&limit=10&sort_key=create_time&sort_dir=desc&instance_ids=id1&instance_ids=id2

Querying the real-time synchronization task list using multiple task IDs

https://{endpoint}/v5/5237e10fe9aa4ad5b16b6a5245248314/jobs?name=bee869bc-15c0-4b3b-a34b-bf0d5efjb201,c2a61a77-6e55-4cd8-8be1-a562cc6jb201&job_type=sync

Example Response

Status code: 200

{
  "jobs" : [ {
    "id" : "c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r",
    "name" : "DRS-1234",
    "status" : "CONFIGURATION",
    "create_time" : "2022-11-07T16:15:18Z",
    "engine_type" : "oracle-to-gaussdbv5",
    "job_direction" : "up",
    "task_type" : "FULL_INCR_TRANS",
    "job_action" : {
      "available_actions" : [ "FREE_RESOURCE", "PRE_CHECK", "MODIFY_CONFIGURATION", "CHANGE" ],
      "unavailable_actions" : [ "CREATE", "START", "CHOOSE_OBJECT", "RETRY", "RESET", "DELETE", "QUERY_PRE_CHECK", "CHANGE_MODE", "MODIFY_DB_CONFIG", "SWITCH_OVER", "RESET_DB_PWD", "PAUSE", "JUMP_RETRY", "START_INCR", "MODIFY_TASK_NUMBER", "CONTINUE_JOB", "STOP_JOB", "CONTINUE_CAPTURE", "STOP_CAPTURE", "CONTINUE_APPLY", "API_CONFIGURATION_ACTION", "STOP_APPLY", "PAY_ORDER", "UNSUBSCRIBE", "TO_PERIOD", "TO_RENEW", "ORDER_INFO", "CLONE" ],
      "current_action" : null
    }
  } ],
  "total_count" : 1
}

Status code: 400

Bad Request

{
  "error_code" : "DRS.10000001",
  "error_msg" : "Failed."
}

Status Code

Status Code	Description
200	OK
400	Bad Request

Error Code

For details, see Error Code.

Parent topic:Task Management

Previous topic: Creating a Task

Next topic: Updating Details About a Task with a Specified ID

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

For any further questions, feel free to contact us through the chatbot.

Chatbot