All Products
Search
Document Center

DataWorks:GetTaskInstance

Last Updated:Oct 09, 2026

Retrieves the details of a specified task instance.

Operation description

You must purchase DataWorks Basic Edition or later to use this feature.

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

dataworks:*

get

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

Id

integer

Yes

The unique identifier of the task instance.

1234

Response elements

Element

Type

Description

Example

object

The response structure.

RequestId

string

The ID of the request. You can use the ID to locate logs and troubleshoot issues.

22C97E95-F023-56B5-8852-B1A77****

TaskInstance

object

The details of the task instance.

TaskId

integer

The ID of the task.

1234

TaskType

string

The type of the task.

ODPS_SQL

TaskName

string

The name of the task.

SQL node

Description

string

The description.

test

WorkflowId

integer

The ID of the workflow to which the task instance belongs.

1234

WorkflowName

string

The name of the workflow to which the task instance belongs.

Test workflow

TriggerType

string

The trigger type. You can obtain the trigger type from the Trigger.Type response parameter of the GetTask operation. Valid values:

  • Scheduler: The task is triggered by a scheduling cycle.

  • Manual: The task is triggered manually.

Scheduler

TriggerRecurrence

string

The run mode upon trigger. This parameter takes effect only when TriggerType is set to Scheduler. Valid values:

  • Normal: The task is a normal scheduled task and is scheduled on a daily basis.

  • Manual: The task is a manual task and is not scheduled on a daily basis.

  • Pause: The task is paused. It is scheduled on a daily basis, but is directly set to failed when the scheduling is triggered.

  • Skip: The task performs a dry run. It is scheduled on a daily basis, but is directly set to successful when the scheduling is triggered.

  • SkipUnchoose: The task is an unselected task in a temporary workflow. It exists only in temporary workflows and is directly set to successful when the scheduling is triggered.

  • SkipCycle: The task is a weekly or monthly task that has not reached its execution cycle. It is scheduled on a daily basis, but is directly set to successful when the scheduling is triggered.

  • ConditionUnchoose: The downstream node is not selected by an upstream branch (IF) node. The task is directly set to a dry run.

  • RealtimeDeprecated: The task is an expired periodic instance generated in real time. It is directly set to successful.

  • PauseCalendar: The instance is paused due to a referenced calendar.

  • SkipCalendar: The instance performs a dry run due to a referenced calendar.

Normal

WorkflowInstanceId

integer

The ID of the workflow instance to which the task instance belongs.

1234

WorkflowInstanceType

string

The type of the workflow instance to which the task instance belongs. Valid values:

  • SmokeTest: The instance is a smoke test.

  • SupplementData: The instance is for data backfill.

  • Manual: The instance is a manual task.

  • ManualWorkflow: The instance is a manual workflow.

  • Normal: The instance uses periodic scheduling.

  • ManualFlow: The instance is a manually executed business flow.

Normal

UnifiedWorkflowInstanceId

integer

The unified workflow instance ID. The value of this field is the same for all task instances within a specific business date under a single trigger.

1234

Timeout

integer

The timeout period for task execution, in seconds.

Note: The scheduling system rounds the configured value to the nearest hour.

3600

RerunMode

string

The configuration that specifies whether the task can be rerun. Valid values:

  • AllDenied: The task cannot be rerun regardless of whether it fails or succeeds.

  • AllAllowed: The task can be rerun regardless of whether it fails or succeeds.

  • FailureAllowed: The task can be rerun only if it fails.

AllAllowed

RunNumber

integer

The current number of runs. Default value: 1.

1

PeriodNumber

integer

The period number. This indicates the sequence of the execution cycle for the task instance on the current day.

1

BaselineId

integer

The baseline ID.

1234

Priority

integer

The execution priority of the task. Valid values: 1 to 8. A larger value indicates a higher priority. Default value: 1.

1

Script

object

The information about the execution script.

Content

string

The content of the script.

echo "helloWorld"

Parameters

string

The list of script parameters.

para1=$bizdate

RuntimeResource

object

The information about the resource group associated with the instance.

ResourceGroupId

string

The identifier of the scheduling resource group configured for task execution.

S_res_group_524258031846018_1684XXXXXXXXX

Image

string

The ID of the image configured for task execution.

i-xxxxxx

Cu

string

The compute unit (CU) consumption configured for task execution.

0.25

Runtime

object

The runtime information of the instance.

ProcessId

string

The unique ID of the execution process.

T3_123

Gateway

string

The machine on which the task is executed.

cn-shanghai.1.2

DataSource

object

The information about the data source associated with the instance.

Name

string

The name of the data source.

mysql_test

Inputs

object

The input information.

Variables

array<object>

The list of variable definitions.

object

The list of variable definitions.

Name

string

The name of the variable.

Key1

Type

string

The type of the variable. Valid values:

  • Constant: The variable is a constant.

  • PassThrough: The variable is the output of a parameter node.

  • System: The variable is a system variable.

  • NodeOutput: The variable is the script output.

Constant

Value

string

The value of the variable.

Value1

Outputs

object

The output information.

TaskOutputs

array<object>

The list of task output definitions.

object

The list of task output definitions.

Output

string

The output identifier.

pre.odps_sql_demo_0

Variables

array<object>

The list of variable definitions.

object

The list of variable definitions.

Name

string

The name of the variable.

key1

Type

string

The type of the variable. Valid values:

  • Constant: The variable is a constant.

  • PassThrough: The variable is the output of a parameter node.

  • System: The variable is a system variable.

  • NodeOutput: The variable is the script output.

Constant

Value

string

The value of the variable.

value1

Tags

array<object>

The list of task tags.

object

The list of task tags.

Key

string

The tag key.

key1

Value

string

The tag value.

value1

Status

string

The running status of the instance. Valid values:

  • NotRun: Not run.

  • Running: Running.

  • WaitTime: Waiting for the trigger time.

  • CheckingCondition: Checking branch conditions.

  • WaitResource: Waiting for resources.

  • Failure: Execution failed.

  • Success: Execution succeeded.

  • Checking: Submitted for data quality check.

  • WaitTrigger: Waiting for an external trigger. Triggered nodes change to this status after the waiting time.

Success

TriggerTime

integer

The scheduled trigger time. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

Bizdate

integer

The business date. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

StartedTime

integer

The start time. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

FinishedTime

integer

The completion time. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

Id

integer

The unique identifier of the task instance.

1234

ProjectId

integer

The project ID.

100

ProjectEnv

string

The project environment. Valid values:

  • Prod: Production.

  • Dev: Development.

Prod

Owner

string

The account ID of the task owner.

1000

CreateTime

integer

The creation time. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

ModifyTime

integer

The update time. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

CreateUser

string

The account ID of the user who created the instance.

1000

ModifyUser

string

The account ID of the user who updated the instance.

1000

WaitingResourceTime

integer

The time when the instance starts waiting for resources.

1710239005403

WaitingTriggerTime

integer

The time when the instance starts waiting for the scheduled trigger. The value is a 13-digit UNIX timestamp in milliseconds.

1710239005403

OperationType

string

The type of the latest operation on the instance.

TriggerDqc

Examples

Success response

JSON format

{
  "RequestId": "22C97E95-F023-56B5-8852-B1A77****",
  "TaskInstance": {
    "TaskId": 1234,
    "TaskType": "ODPS_SQL",
    "TaskName": "SQL node\n",
    "Description": "test",
    "WorkflowId": 1234,
    "WorkflowName": "Test workflow",
    "TriggerType": "Scheduler",
    "TriggerRecurrence": "Normal",
    "WorkflowInstanceId": 1234,
    "WorkflowInstanceType": "Normal",
    "UnifiedWorkflowInstanceId": 1234,
    "Timeout": 3600,
    "RerunMode": "AllAllowed",
    "RunNumber": 1,
    "PeriodNumber": 1,
    "BaselineId": 1234,
    "Priority": 1,
    "Script": {
      "Content": "echo \"helloWorld\"",
      "Parameters": "para1=$bizdate"
    },
    "RuntimeResource": {
      "ResourceGroupId": "S_res_group_524258031846018_1684XXXXXXXXX",
      "Image": "i-xxxxxx",
      "Cu": "0.25"
    },
    "Runtime": {
      "ProcessId": "T3_123",
      "Gateway": "cn-shanghai.1.2"
    },
    "DataSource": {
      "Name": "mysql_test"
    },
    "Inputs": {
      "Variables": [
        {
          "Name": "Key1",
          "Type": "Constant",
          "Value": "Value1"
        }
      ]
    },
    "Outputs": {
      "TaskOutputs": [
        {
          "Output": "pre.odps_sql_demo_0"
        }
      ],
      "Variables": [
        {
          "Name": "key1",
          "Type": "Constant",
          "Value": "value1"
        }
      ]
    },
    "Tags": [
      {
        "Key": "key1",
        "Value": "value1"
      }
    ],
    "Status": "Success",
    "TriggerTime": 1710239005403,
    "Bizdate": 1710239005403,
    "StartedTime": 1710239005403,
    "FinishedTime": 1710239005403,
    "Id": 1234,
    "ProjectId": 100,
    "ProjectEnv": "Prod",
    "Owner": "1000",
    "CreateTime": 1710239005403,
    "ModifyTime": 1710239005403,
    "CreateUser": "1000",
    "ModifyUser": "1000",
    "WaitingResourceTime": 1710239005403,
    "WaitingTriggerTime": 1710239005403,
    "OperationType": "TriggerDqc"
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.