Listing Jobs

Function

This API is used to list the current user's jobs. You can set the job ID as the ID and query jobs whose IDs are greater than or less than the ID. You can also query jobs in specific status, for example, in running status or other. By default, all jobs are queried.

Authorization

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 the required permissions in Introduction.
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
dli:jobs:list

list

jobs *

-

-

-
-

g:RequestTag/<tag-key>

g:TagKeys

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependency
dli:jobs:list	list	jobs *	-	-	-
-	g:RequestTag/<tag-key> g:TagKeys	-	-

URI

URI format
GET /v1.0/{project_id}/streaming/jobs

Parameter description

**Table 1** URI parameter
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID, which is used for resource isolation. For details about how to obtain its value, see Obtaining a Project ID. Example: 48cc2c48765f481480c7db940d6409d1 Constraints N/A Range The value can contain up to 64 characters. Only letters and digits are allowed. Default Value N/A

**Table 2** query parameter descriptions
Parameter	Mandatory	Type	Description
job_type	No	String	Definition Job type. Constraints N/A Range flink_sql_job: Flink SQL job flink_opensource_sql_job: Flink OpenSource SQL job flink_jar_job: User-defined Flink job Default Value N/A
status	No	String	Definition Job status. Constraints N/A Range job_init: The job is in the draft state. job_submitting: The job is being submitted. job_submit_fail: The job fails to be submitted. job_running: The job is running. (The billing starts. After the job is submitted, a normal result is returned.) job_running_exception (The billing stops. The job stops running due to an exception.) job_downloading: The job is being downloaded. job_idle: The job is idle. job_canceling: The job is being stopped. job_cancel_success: The job has been stopped. job_cancel_fail: The job fails to be stopped. job_savepointing: A savepoint is being created. job_arrearage_stopped: The job is stopped because the account is in arrears. (The billing ends. The job is stopped because the user account is in arrears.) job_arrearage_recovering: The recharged job is being restored. (The account in arrears is recharged, and the job is being restored). job_finish: The job is completed. Default Value N/A
queue_name	No	String	Definition Queue name. Constraints N/A Range N/A Default Value N/A
order	No	String	Definition Sorting style of the query results. Constraints N/A Range asc: by time in ascending order desc: by time in descending order Default Value The default value is desc.
limit	No	Integer	Definition Number of returned data records. Constraints The maximum value is 100. Range 0-100 Default Value The default value is 10.
name	No	String	Definition Job name. Constraints The value can contain 0 to 57 characters. Range N/A Default Value N/A
offset	No	Integer	Definition Job offset. Constraints N/A Range N/A Default Value N/A
show_detail	No	Boolean	Definition Whether to return job details. The default value is false. If this parameter is set to true, the job details are returned. For details, see Querying Job Details. Constraints N/A Range N/A Default Value false
user_name	No	String	Definition Username, which can be used as a filter. Constraints N/A Range N/A Default Value N/A
tags	No	String	Definition Tag for filtering. Constraints N/A Range N/A Default Value N/A

Request Parameters

None

Response Parameters

**Table 3** Response parameters
Parameter	Mandatory	Type	Description
is_success	No	String	Definition Whether the request was successfully executed. Range true indicates that the request was successfully executed. false indicates that the request execution failed.
message	No	String	Definition System prompt. If the execution succeeded, this parameter is left blank. Range N/A
job_list	No	Object	Definition Job list information. For details, see Table 4. Range N/A

**Table 4** job_list parameters
Parameter	Mandatory	Type	Description
total_count	No	Integer	Definition Number of records in the query result. Range N/A
jobs	No	Array of objects	Definition Job information. For details, see Table 5. Range N/A

**Table 5** **Jobs** parameters
Parameter	Mandatory	Type	Description
job_id	No	Long	Definition Job ID. Range N/A
name	No	String	Definition Job name. Range The value can contain 0 to 57 characters.
desc	No	String	Definition Job description. Range The value can contain 0 to 512 characters.
user_name	No	String	Definition Username. This parameter is valid only when show_detail is set to false. Range The value can contain up to 128 characters.
job_type	No	String	Definition Job type. Range flink_sql_job: Flink SQL job. flink_opensource_sql_job: Flink OpenSource SQL job. flink_jar_job: User-defined Flink job.
status	No	String	Definition Job status. Range job_init: The job is in the draft state. job_submitting: The job is being submitted. job_submit_fail: The job fails to be submitted. job_running: The job is running. job_running_exception: The job is running abnormally. job_downloading: The job is being downloaded. job_idle: The job is idle. job_canceling: The job is being stopped. job_cancel_success: The job has been stopped. job_cancel_fail: The job fails to be stopped. job_savepointing: A savepoint is being created. job_arrearage_stopped: The job is stopped due to arrears. job_arrearage_recovering: The job in arrears is being restored. job_finish: The job is completed.
status_desc	No	String	Definition Job status description. Range N/A
create_time	No	Long	Definition Time when a job is created. Example: 1516952770835 Range An integer greater than or equal to 0
start_time	No	Long	Definition Job start time. The value 0 indicates that the process is not started. Example: 1516952710740 Range An integer greater than or equal to 0
duration	No	Long	Definition Job running duration. Unit: ms. This parameter is valid only when show_detail is set to false. Range An integer greater than or equal to 0
root_id	No	Long	Definition Parent job ID. This parameter is valid only when show_detail is set to false. Range N/A
graph_editor_enabled	No	Boolean	Definition Whether the stream graph of a job can be edited. Value true indicates that the stream graph can be edited, and false indicates that the stream graph cannot be edited. Range N/A
has_savepoint	No	Boolean	Definition Whether a job has a savepoint. Value true indicates that the job has a savepoint, and false indicates that the job does not have a savepoint. Range N/A
user_id	No	String	Definition ID of the user who creates the job. This parameter is valid only when show_detail is set to true. Range N/A
project_id	No	String	Definition ID of the project to which a job belongs. This parameter is valid only when show_detail is set to true. Range N/A
sql_body	No	String	Definition Stream SQL statement. This parameter is returned only when show_detail is set to true. Range N/A
run_mode	No	String	Definition Job running mode. The options are as follows: The value can be shared_cluster, exclusive_cluster, or edge_node. This parameter is valid only when show_detail is set to true. Range shared_cluster: indicates that the job is running on a shared cluster. exclusive_cluster: indicates that the job is running on an exclusive cluster. edge_node: indicates that the job is running on an edge node.
job_config	No	Object	Definition Job configuration. This parameter is returned only when show_detail is set to true. For details about the parameters, see Table 6. Range N/A
main_class	No	String	Definition Main class of a JAR file. This parameter is returned only when show_detail is set to true. Range N/A
entrypoint_args	No	String	Definition Job running parameter of the JAR file. Multiple parameters are separated by spaces. This parameter is valid only when show_detail is set to true. Range N/A
execution_graph	No	String	Definition Job execution plan. This parameter is returned only when show_detail is set to true. Range N/A
update_time	No	Long	Definition Job update time. This parameter is returned only when show_detail is set to true. Range N/A
queue_name	No	String	Definition Queue name. Range N/A
edge_group_ids	No	Array of strings	Definition List of edge computing group IDs. Use commas (,) to separate multiple IDs. Range N/A
restart_times	No	Integer	Definition Number of restarts. Range N/A
savepoint_path	No	String	Definition Path for storing manually generated checkpoints. Range N/A

**Table 6** **job_config** parameters
Parameter	Mandatory	Type	Description
checkpoint_enabled	No	Boolean	Definition Whether to enable automatic job snapshots. Range true: enabled false: disabled The default value is false.
checkpoint_mode	No	String	Definition: Snapshot mode. Range Options: exactly_once: indicates that data is processed only once. at_least_once: indicates that data is processed at least once. The default value is exactly_once.
checkpoint_interval	No	Integer	Definition Snapshot interval. The unit is second. The default value is 10. Range N/A
log_enabled	No	Boolean	Definition Whether to enable log storage. The default value is false. Range true: Enable log storage. false: Disable log storage.
obs_bucket	No	String	Definition OBS bucket name. Range N/A
smn_topic	No	String	Definition SMN topic name. If a job fails, the system will send a message to users subscribed to this SMN topic. Range N/A
root_id	No	Integer	Definition Parent job ID. Range N/A
edge_group_ids	No	Array of strings	Definition List of edge computing group IDs. Use commas (,) to separate multiple IDs. Range N/A
manager_cu_number	No	Integer	Definition Number of CUs of the management unit. The default value is 1. Range N/A
cu_number	No	Integer	Definition Number of CUs selected for a job. This parameter is valid only when show_detail is set to true. Minimum value: 2 Maximum value: 400 The default value is 2. Range N/A
parallel_number	No	Integer	Definition Number of parallel jobs set by a user. This parameter is valid only when show_detail is set to true. Minimum value: 1 Maximum value: 2000 The default value is 1. Range N/A
restart_when_exception	No	Boolean	Definition Whether to enable restart on exceptions. Range N/A
idle_state_retention	No	Integer	Definition Expiration time. Range N/A
udf_jar_url	No	String	Definition Name of the package that has been uploaded to the DLI resource management system. The UDF Jar file of the SQL job is uploaded through this parameter. Range N/A
dirty_data_strategy	No	String	Definition Dirty data policy of a job. Range 2:obsDir: Save. obsDir specifies the path for storing dirty data. 1: Trigger a job exception 0: Ignore
entrypoint	No	String	Definition Name of the package that has been uploaded to the DLI resource management system. This parameter is used to customize the JAR file where the job main class is located. Range N/A
dependency_jars	No	Array of strings	Definition Name of the package that has been uploaded to the DLI resource management system. This parameter is used to customize other dependency packages. Range N/A
dependency_files	No	Array of strings	Definition Name of the resource package that has been uploaded to the DLI resource management system. This parameter is used to customize dependency files. Range N/A
executor_number	No	Integer	Definition Number of compute nodes used by a job. Range N/A
executor_cu_number	No	Integer	Definition Number of CUs on a compute node. Range N/A
execution_agency_urn	No	String	Definition Name of the agency authorized to DLI. This parameter is configurable in Flink 1.15. Range N/A
resume_checkpoint	No	Boolean	Definition Whether to restore data from the latest checkpoint when the system automatically restarts upon an exception. The default value is false. Range N/A
runtime_config	No	String	Definition Custom optimization parameters for Flink job runtime. Range N/A
graph_editor_enabled	No	Boolean	Definition Whether to enable stream graph editing. The default value is false. Range N/A
graph_editor_data	No	String	Definition Edited stream graph data. The default value is null. Range N/A
resume_max_num	No	Integer	Definition Maximum retries on exceptions. –1 indicates there is no upper limit. Range N/A
checkpoint_path	No	String	Definition Checkpoint save path. Range N/A
config_url	No	String	Definition OBS path of the config package uploaded by the user. Range N/A
tm_cus	No	int	Definition Number of CUs per TaskManager node. Range N/A
tm_slot_num	No	int	Definition Number of slots per TaskManager node. Range N/A
image	No	String	Definition Custom image. The format is Organization name/Image name:Image version. This parameter is valid only when feature is set to custom. You can use this parameter with the feature parameter to specify a user-defined Flink image for job running. For details about how to use custom images, see Data Lake Insight User Guide. Range N/A
feature	No	String	Definition Custom job feature. Type of the Flink image used by a job. Range basic: indicates that the basic Flink image provided by DLI is used. custom: indicates that the user-defined Flink image is used.
flink_version	No	String	Definition Flink version. This parameter is valid only when feature is set to basic. You can use this parameter with the feature parameter to specify the version of the DLI basic Flink image used for job running. Range N/A
operator_config	No	String	Definition Operator's parallelism degree. The operator ID and degree of parallelism are displayed in JSON format. Range N/A
static_estimator_config	No	String	Definition Resource estimation for the static stream graph, which is displayed in JSON format. Range N/A
real_cu_number	No	Integer	Definition Number of actually used CUs. The default value is 0, indicating that the value of cu_number is used. Range N/A
resource_config_version	No	String	Definition Resource configuration version. Range: v1 (default) or v2. Compared with the v1 template, the v2 template does not support the setting of the number of CUs. The v2 template supports the setting of Job Manager Memory and Task Manager Memory. Range v1: applicable to Flink 1.12 and 1.15. v2: applicable to Flink 1.15 and 1.17. You are advised to use the parameter settings of v2.
resource_config	No	Object	Definition Resource configuration of a Flink job. Range For details about the parameters, see Table 7. When the resource configuration version is v2, the configuration takes effect; when the resource configuration version is v1, the configuration is invalid.
flink_log_config	No	String	Definition Configuration logs and status. This parameter is supported in Flink 1.15 or later. Range root_logger_level and loggers_level_of_class For details about the log levels, see Table 10. root_logger_level The log level determines the importance and urgency of log messages. The root log level serves as a global setting, providing a default log level for the entire application. If no specific log level is configured for a particular logger or class, the root log level will be applied. For example, if the root log level is set to INFO, all loggers without individual configurations will output logs at the INFO level or higher. Log levels are prioritized from low to high as follows: TRACE < DEBUG < INFO < WARN < ERROR < FATAL. In practice, log levels can be used to filter and display log information effectively. Example: During development, TRACE and DEBUG levels may be enabled for detailed insights. In production environments, only INFO, WARN, and ERROR levels are typically enabled to reduce log file size and improve performance. loggers_level_of_class A class log level refers to a log level specifically assigned to a particular class or package. It enables finer-grained control over logging for different classes or packages. By configuring a class log level, you can obtain more detailed logs for specific classes or packages without affecting other parts of the system. For example, during debugging, you might set the log level of a critical class to DEBUG to gather additional debugging information. Configuration example {"root_logger_level":"INFO","loggers_level_of_class":{"org.apache.flink":"WARN","org.apache.kafka.clients.consumer.KafkaConsumer":"DEBUG","com.mycompany.job.MainFunction":"TRACE"}}

**Table 7** resource_config parameter descriptions
Parameter	Mandatory	Type	Description
max_slot	No	Integer	Definition Number of parallel tasks that a single TaskManager can support. Each task slot can execute one task in parallel. Increasing task slots enhances the parallel processing capacity of the TaskManager but also increases resource consumption. The number of task slots is linked to the CPU count of the TaskManager since each CPU can offer one task slot. Range By default, a single TM slot is set to 1. The minimum parallelism must not be less than 1.
parallel_number	No	Integer	Definition Number of tasks concurrently executed by each operator in a job. Range The default value is 1.
jobmanager_resource_spec	No	Object	Definition JobManager resource specifications. Range For details about the parameters, see Table 8.
taskmanager_resource_spec	No	Object	Definition TaskManager resource specifications. Range For details about the parameters, see Table 9.

**Table 8** jobmanager_resource_spec parameter descriptions
Parameter	Mandatory	Type	Description
cpu	No	Double	Definition Number of CPU cores available for JobManager. Range The default value is 1.0 CPU core, with a minimum of no less than 0.5 CPU cores. If the current job is running on a basic edition elastic resource pool (16–64 CUs), it is recommended that the JobManager's CPU value not exceed 2 to avoid resource scheduling failures during job execution.
memory	No	String	Definition Memory that can be used by JobManager, in MB or GB. The default unit is GB. Range The default value is 4 GB, and the minimum value is 2 GB.

**Table 9** taskmanager_resource_spec parameter descriptions
Parameter	Mandatory	Type	Description
cpu	No	Double	Definition Number of CPU cores available for TaskManager. Range The default value is 1.0 CPU core, with a minimum of no less than 0.5 CPU cores. If the current job is running on a basic edition elastic resource pool (16–64 CUs), it is recommended that the TaskManager's CPU value not exceed 2 to avoid resource scheduling failures during job execution.
memory	No	String	Definition Memory that can be used by TaskManager, in MB or GB. The default unit is GB. Range The default value is 4 GB, and the minimum value is 2 GB.

**Table 10** Root log levels
Level	Description	Use Case
TRACE	The most granular level of logging, typically used during development and debugging. It captures all operational details, including variable values and function calls.	Primarily for the development phase to help developers understand code execution flow and state.
DEBUG	Less detailed than TRACE, intended for debugging purposes. It logs program runtime states and key variable values but omits exhaustive detail.	Mainly used during development and testing phases to assist developers in identifying issues.
INFO	Records important information during normal operations, useful for system operators and maintainers without impacting system functionality.	Tracks major system operations and statuses, such as startup, shutdown, and configuration changes.
WARN	Potential issues or anomalies that do not disrupt system operation but warrant attention from developers or operators.	Logs situations that may affect system performance or functionality, serving as a warning for possible problems.
ERROR	Highlights critical issues or exceptions that impair system functionality and require immediate resolution.	Captures errors and exceptions during system operation, enabling developers to quickly identify and address them.

Example Request

N/A

Example Response

{
    "is_success": "true",
    "message": "Jobs are successfully listed.",
    "job_list": {
        "total_count": 26,
        "jobs": [
            {
                "job_id": 146,
                "name": "aaaaa",
                "desc": "",
                "user_name": "testuser",
                "job_type": "flink_sql_job",
                "status": "job_init",
                "status_desc": "",
                "create_time": 1578892414688,
                "duration": 0,
                "root_id": -1,
                "graph_editor_enabled": false,
                "has_savepoint": false
            }
        ]
    }
}

Status Codes

Table 11 describes status codes.

**Table 11** Status codes
Status Code	Description
200	Job list query succeeds.
400	The input parameter is invalid.

Error Codes

If an error occurs when this API is called, the system does not return the result similar to the preceding example, but returns an error code and error message. For details, see Error Codes.

Parent topic: Flink Job-related APIs

Previous topic: Batch Running Jobs

Next topic: Querying Job Details

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