Help Center/ MapReduce Service/ API Reference/ API V2/ Job Management APIs/ Querying a List of Jobs - ShowJobList
Updated on 2026-09-15 GMT+08:00

Querying a List of Jobs - ShowJobList

Function

This API is used to query the list of jobs submitted in the job management of a specified MRS cluster. It supports filtering by job status and job type, and is used to monitor and manage the running status of jobs in the cluster.

Constraints

None

Debugging

You can debug this API in API Explorer. Automatic authentication is supported. API Explorer can automatically generate sample SDK code and supports sample SDK code debugging.

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 Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependency

    mrs:cluster:getJob

    Read

    cluster *

    • g:ResourceTag/<tag-key>

    • g:EnterpriseProjectId

    • mrs:job:get

    -

URI

GET /v2/{project_id}/clusters/{cluster_id}/job-executions
Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Constraints

N/A

Range

The value must consist of 1 to 64 characters. Only letters and digits are allowed.

Default Value

N/A

cluster_id

Yes

String

Definition

Cluster ID. For details about how to obtain the cluster ID, see Obtaining a Cluster ID.

Constraints

N/A

Range

The value can contain 1 to 64 characters, including only letters, digits, underscores (_), and hyphens (-).

Default Value

N/A

Table 2 Query parameters

Parameter

Mandatory

Type

Description

job_name

No

String

Definition

Job name.

Constraints

N/A

Range

The value can contain 1 to 128 characters, including only letters, digits, underscores (_), and hyphens (-).

Default Value

N/A

job_id

No

String

Definition

Job ID. For details about how to obtain it, see Obtaining a Job ID.

Constraints

N/A

Range

The value can contain 1 to 64 characters, including only letters, digits, and hyphens (-).

Default Value

N/A

user

No

String

Definition

Username.

Constraints

N/A

Range

The value can contain 1 to 32 characters, including only letters, digits, hyphens (-), underscores (_), and periods (.), and cannot start with a digit.

Default Value

N/A

job_type

No

String

Definition

Job type.

Constraints

N/A

Range

  • MapReduce: provides a distributed data processing model and execution environment capable of rapidly handling large-scale data in parallel. With MRS, you can submit MapReduce JAR programs.

  • SparkSubmit: allows you to submit Spark JAR and Spark Python programs and run Spark applications to compute and process user data.

  • SparkPython: SparkPython jobs are converted to SparkSubmit jobs for submission. On the MRS console, the job type is displayed as SparkSubmit. When calling an API to query the job list, select SparkSubmit.

  • HiveScript: an open-source data warehouse that runs on Hadoop. With MRS, you can submit HiveScript scripts for execution.

  • HiveSql: an open-source data warehouse that runs on Hadoop. With MRS, you can directly execute Hive SQL statements.

  • DistCp: a Hadoop tool used to efficiently import and export data between distributed file systems (such as HDFS).

  • SparkScript: allows you to submit SparkScript scripts and batch execute Spark SQL statements.

  • SparkSql: allows you to run SQL-like statements provided by Spark to query and analyze user data in real time.

  • Flink: a distributed big data processing engine that can perform stateful computations over both unbounded and bounded data streams.

Default Value

N/A

job_state

No

String

Definition

The job execution status.

Constraints

N/A

Range

  • FAILED: indicates that the job fails to be executed.
  • KILLED: indicates that the job is terminated.
  • New: indicates that the job is created.
  • NEW_SAVING: indicates that the job has been created and is being saved.
  • SUBMITTED: indicates that the job is submitted.
  • ACCEPTED: indicates that the job is accepted.
  • RUNNING: indicates that the job is running.
  • FINISHED: indicates that the job is completed.

Default Value

N/A

job_result

No

String

Definition

Job execution result.

Constraints

N/A

Range

  • FAILED: indicates that the job fails to be executed.
  • KILLED: indicates that the job is manually terminated during execution.
  • UNDEFINED: indicates that the job is being executed.
  • SUCCEEDED: indicates that the job has been successfully executed.

Default Value

N/A

queue

No

String

Definition

Resource queue type of a job.

Constraints

N/A

Range

The value can contain 1 to 64 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. The default value is default.

Default Value

default

limit

No

String

Definition

Number of records displayed on each page in the returned result.

Constraints

N/A

Range

1~100

Default Value

10

offset

No

String

Definition

Offset from which the job list starts to be queried.

Constraints

N/A

Range

N/A

Default Value

1

sort_by

No

String

Definition

Sorting method of the returned result.

Constraints

N/A

Range

  • asc: indicates that the returned results are sorted in ascending order.
  • desc: indicates that the returned results are sorted in descending order.

Default Value

desc

submitted_time_begin

No

Long

Definition

UTC timestamp after which a job is submitted, in milliseconds, for example, 1562032041362.

Constraints

N/A

Range

N/A

Default Value

N/A

submitted_time_end

No

Long

Definition

UTC timestamp before which a job is submitted, in milliseconds, for example, 1562032041362.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 202

Table 3 Response body parameters

Parameter

Type

Description

total_record

Integer

Definition

Total number of records.

Range

N/A

job_list

Array of JobQueryBean objects

Definition

The job list. For details about the parameters, see Table 4.

Range

N/A

Table 4 JobQueryBean

Parameter

Type

Description

job_id

String

Definition

Job ID.

Range

N/A

user

String

Definition

Name of the user who submits the job.

Range

N/A

job_name

String

Definition

Job name.

Range

N/A

job_result

String

Definition

Final result of a job.

Range

  • FAILED: indicates that the job fails to be executed.
  • KILLED: indicates that the job is manually terminated during execution.
  • UNDEFINED: indicates that the job is being executed.
  • SUCCEEDED: indicates that the job has been successfully executed.

job_state

String

Definition

Job execution status.

Range

  • FAILED: indicates that the job fails to be executed.
  • KILLED: indicates that the job is terminated.
  • New: indicates that the job is created.
  • NEW_SAVING: indicates that the job has been created and is being saved.
  • SUBMITTED: indicates that the job is submitted.
  • ACCEPTED: indicates that the job is accepted.
  • RUNNING: indicates that the job is running.
  • FINISHED: indicates that the job is completed.

job_progress

Float

Definition

Job execution progress.

Range

N/A

job_type

String

Definition

Job type.

Range

  • MapReduce: provides a distributed data processing model and execution environment capable of rapidly handling large-scale data in parallel. With MRS, you can submit MapReduce JAR programs.

  • SparkSubmit: allows you to submit Spark JAR and Spark Python programs and run Spark applications to compute and process user data.

  • SparkPython: SparkPython jobs are converted to SparkSubmit jobs for submission. On the MRS console, the job type is displayed as SparkSubmit. When calling an API to query the job list, select SparkSubmit.

  • HiveScript: an open-source data warehouse that runs on Hadoop. With MRS, you can submit HiveScript scripts for execution.

  • HiveSql: an open-source data warehouse that runs on Hadoop. With MRS, you can directly execute Hive SQL statements.

  • DistCp: a Hadoop tool used to efficiently import and export data between distributed file systems (such as HDFS).

  • SparkScript: allows you to submit SparkScript scripts and batch execute Spark SQL statements.

  • SparkSql: allows you to run SQL-like statements provided by Spark to query and analyze user data in real time.

  • Flink: a distributed big data processing engine that can perform stateful computations over both unbounded and bounded data streams.

started_time

Long

Definition

Time when a job starts to execute. Unit: milliseconds

Range

N/A

submitted_time

Long

Definition

Time when a job is submitted. Unit: milliseconds

Range

N/A

finished_time

Long

Definition

Time when a job was completed. Unit: milliseconds

Range

N/A

elapsed_time

Long

Definition

Running duration of a job. Unit: milliseconds

Range

N/A

arguments

String

Definition

Running parameter.

Range

N/A

properties

String

Definition

Configuration parameter, which is used to configure -d parameters.

Range

N/A

launcher_id

String

Definition

Actual job ID.

Range

N/A

app_id

String

Definition

Actual job ID.

Range

N/A

tracking_url

String

Definition

The URL for accessing logs. Currently, only SparkSubmit jobs support this parameter. This parameter accesses the Yarn Web UI via the EIP bound to the cluster. If the EIP is unbound from the cluster on the VPC console, the MRS service data is not updated in a timely manner and the access fails. In this case, you can bind the EIP to the cluster again to rectify the fault.

Range

N/A

queue

String

Definition

Resource queue type of a job.

Range

The value can contain 1 to 64 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed, for example, default.

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

Range

400: The operation failed.

error_msg

String

Definition

Error message.

Range

400: The operation failed.

Example Request

Example request for listing jobs.

GET https://{endpoint}/v2/{project_id}/clusters/{cluster_id}/job-executions

Example Response

Status code: 202

Querying a list of jobs is successful.

{
  "total_record" : 2,
  "job_list" : [ {
    "job_id" : "981374c1-85da-44ee-be32-edfb4fba776c",
    "user" : "xxxx",
    "job_name" : "SparkSubmitTset",
    "job_result" : "UNDEFINED",
    "job_state" : "ACCEPTED",
    "job_progress" : 0,
    "job_type" : "SparkSubmit",
    "started_time" : 0,
    "submitted_time" : 1564714763119,
    "finished_time" : 0,
    "elapsed_time" : 0,
    "queue" : "default",
    "arguments" : "[--class, --driver-memory, --executor-cores, --master, yarn-cluster, s3a://obs-test/hadoop-mapreduce-examples-3.1.1.jar, dddd]",
    "launcher_id" : "application_1564622673393_0613",
    "properties": "{mrs.cluster.is.user-agency=true}"
  }, {
    "job_id" : "c54c8aa0-c277-4f83-8acc-521d85cfa32b",
    "user" : "xxxx",
    "job_name" : "SparkSubmitTset2",
    "job_result" : "UNDEFINED",
    "job_state" : "ACCEPTED",
    "job_progress" : 0,
    "job_type" : "SparkSubmit",
    "started_time" : 0,
    "submitted_time" : 1564714020099,
    "finished_time" : 0,
    "elapsed_time" : 0,
    "queue" : "default",
    "arguments" : "[--conf, yujjsjhe, --driver-memory, yueujdjjd, --master,\nyarn-cluster,\ns3a://obs-test/hadoop-mapreduce-examples-3.1.1.jar]",
    "launcher_id" : "application_1564622673393_0611",
    "properties": "{mrs.cluster.is.user-agency=true}"
  } ]
}

Status code: 400

Listing jobs failed.

{
  "error_msg": "Failed to query the job list."
  "error_code" : "0166"
}

SDK Sample Code

The SDK sample code is as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.mrs.v2.region.MrsRegion;
import com.huaweicloud.sdk.mrs.v2.*;
import com.huaweicloud.sdk.mrs.v2.model.*;


public class ShowJobExeListNewSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        MrsClient client = MrsClient.newBuilder()
                .withCredential(auth)
                .withRegion(MrsRegion.valueOf("<YOUR REGION>"))
                .build();
        ShowJobExeListNewRequest request = new ShowJobExeListNewRequest();
        request.withClusterId("{cluster_id}");
        try {
            ShowJobExeListNewResponse response = client.showJobExeListNew(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmrs.v2.region.mrs_region import MrsRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkmrs.v2 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = MrsClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(MrsRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ShowJobExeListNewRequest()
        request.cluster_id = "{cluster_id}"
        response = client.show_job_exe_list_new(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    mrs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := mrs.MrsClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := mrs.NewMrsClient(hcClient)

    request := &model.ShowJobExeListNewRequest{}
	request.ClusterId = "{cluster_id}"
	response, err := client.ShowJobExeListNew(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

202

Jobs listed successfully.

400

Listing jobs failed.

Error Codes

See Error Codes.